1. 先把这两个模型能干什么弄清楚再谈怎么跑想把 CogVLM 与 CogAgent 部署到本地最容易踩的第一个坑是以为它们是同一类东西装个环境就能一起用。实际情况差得挺远CogVLM 是通用的视觉语言模型你给它一张图加一句话它给你一段描述、一段分析或者一段 OCR 结果CogAgent 是在前者的底座上继续往 GUI 方向训练出来的智能体模型它看的是截图输出的是“点哪里、输入什么、往下滚多少”这类动作指令。部署 CogVLM 的流程和部署 CogAgent 的流程九成相似但剩下那一成——输入分辨率、prompt 模板、坐标换算——决定了你能不能真正跑起来。我前后在两台机器上折腾了差不多一周第一台是单卡 24G 的消费级卡第二台是双卡 48G 的工作站中间踩的坑基本都集中在显存、依赖版本和坐标映射这三处所以下面按这三条主线展开。先说清楚“本地部署”这件事的价值。很多人第一反应是调接口不就完了何必自己折腾显存和依赖。但实际项目里需要本地跑的场景非常硬内网隔离的机器没有外网、每天要处理几万张截图不能按次计费、需要对模型输出做自由的后处理、需要把模型嵌进已有的自动化流程里当一个小模块用。这些需求叠在一起本地部署就成了唯一解。而 CogVLM 这类模型的好处在于它的权重和推理代码都是开放的你能看到视觉专家模块怎么接进去、图像怎么预处理、tokenizer 怎么拼 prompt这些细节在调效果的时候全是关键。1.1 CogVLM看图说话的通用底座CogVLM 的结构可以拆成三块来理解一块视觉编码器负责把图片变成特征一块语言模型负责生成文字中间还有一个“视觉专家”模块专门在语言模型的若干层里插入可训练的视觉通路。打个比方语言模型是一条跑了很久的高速公路视觉专家相当于在关键路口修了几条匝道让图像信息能就近汇入而不是全部挤在入口处硬塞进去。这个设计带来的直接好处是模型对图像细节的敏感度比“把图像特征拼在 prompt 前面”那种朴素做法要好不少尤其是小字、表格、界面元素这类需要精确读取的内容。对部署者来说这个结构意味着两件事。第一模型总参数量比同级别的纯文本模型大权重占用的显存更多17B 级别的模型在半精度下光权重就要 34GB 上下单卡 24G 根本放不下必须走量化或者多卡。第二它依赖trust_remote_codeTrue加载自定义代码也就是说模型目录里自带建模文件这些文件对transformers的版本相当挑剔版本差一点就可能报出一堆看着莫名其妙的错。后面我会具体说版本怎么选。1.2 CogAgent盯着屏幕找按钮的那一类CogAgent 的定位更垂直。它的输入是一张屏幕截图输出是结构化的动作比如点击某个坐标、在某个位置输入文本、滚动页面。它的图像输入分辨率比通用版更高因为 GUI 界面上的按钮、输入框、图标都很小压缩得太狠模型就看不见了。高分辨率带来的代价是显存和计算量同步上升同样一张图编码出来的视觉 token 数量可能是普通图片的好几倍。部署 CogAgent 时最需要提前想清楚的是坐标系问题。模型是在缩放后的图像上做定位的而你的真实屏幕是原始分辨率两者之间差一个缩放比和一个可能的填充偏移。这个换算如果做错模型明明“看对了”点下去却偏了半个屏幕排查起来非常折磨人。我建议在正式接入自动化流程之前先做一次坐标标定用几个已知位置的元素验证映射关系这一步花十分钟能省掉后面几小时的怀疑人生。1.3 什么配置的机器能跑先说结论很多人卡在第一步不知道自己手上的机器够不够。我把几种常见配置的实际情况列出来方便你对照。注意这里说的是“能跑起来并输出合理结果”不是“能跑得飞快”。模型规模精度权重显存加上激活与KV后的实际占用建议硬件17B 级别bf16约 34GB38GB 到 42GB单卡 48G 或双卡 24G17B 级别4bit 量化约 10GB13GB 到 16GB单卡 24G 可用19B 级别bf16约 38GB42GB 到 46GB单卡 48G双卡更稳19B 级别4bit 量化约 11GB14GB 到 18GB单卡 24G 可跑18B 级别GUI 版4bit 量化约 11GB15GB 到 19GB单卡 24G高分辨率截图更吃显存这张表里的“实际占用”不是拍脑袋后面会给出估算方法。简单说权重只是地基真正把显存撑爆的往往是长 prompt 的 KV Cache 和高分辨率图像产生的视觉 token。一张 1120 见方的截图编码出来的 token 数量可能顶得上几百个中文字做多轮对话时这部分会持续累积。2. 环境这一关版本对齐比装包重要得多我先说一个反直觉的结论这类模型的部署失败八成不是硬件不够是版本不对。你按某个教程装了一套包代码跑起来报AttributeError或者KeyError搜半天发现是transformers小版本差了两位。这种问题没有通用解只能靠锁定版本。我的做法是先在一个干净环境里装最小依赖集跑通官方示例再往里面加东西一旦加出问题立刻回退绝不在一棵已经长歪的树上继续嫁接。2.1 依赖版本的三角关系需要同时对齐的有三样CUDA 驱动、PyTorch、transformers。三者是链式依赖任何一环错位都会在加载模型时炸出来。CUDA 与 PyTorch先看nvidia-smi右上角显示的驱动支持的最高 CUDA 版本然后选一个不高于它的 PyTorch 轮子。驱动支持 12.1你装 cu121 的轮子最省事硬装 cu118 的轮子通常也能跑但要留意量化库有没有对应编译版本。PyTorch 与transformers这一对最容易出事。模型自带的建模代码里会 import 一些内部类新版transformers改了签名就会直接报错。量化库4bit 加载依赖bitsandbytes它需要和 CUDA 运行时匹配版本太旧会报找不到符号。我实测下来比较稳的一组是PyTorch 2.1 到 2.3 区间transformers4.37 到 4.42 区间accelerate0.26 以上bitsandbytes0.41 以上。这个组合不是唯一解但它是个“大多数教程和模型自带代码都能兼容”的安全区。如果你拿到的是更新的模型版本可以适当往上走但务必先用最小脚本验证加载别一上来就跑完整业务。提示不要用pip install -U无脑升级。跑通之后立刻pip freeze requirements.lock把当前环境冻住这是血泪教训。我有一次为了装另一个库顺手升了transformers第二天回来模型加载直接崩回滚花了半小时。2.2 隔离环境与目录规划不要往系统 Python 里装东西这是底线。用 conda 或者 venv 建一个独立环境名字起得直白点比如vlm-local。模型权重体积大一般十几个到几十个 G别放在系统盘找个数据盘建个统一目录mkdir -p /data/models/cogvlm-chat-hf mkdir -p /data/models/cogagent-chat-hf mkdir -p /data/workspace/vlm-demo权重放/data/models下代码放/data/workspace下缓存目录也要单独指出来否则 HuggingFace 默认会往家目录的隐藏文件夹里塞跑几个模型下来把根分区撑满是常有的事。环境变量这样设export HF_HOME/data/hf_cache export TRANSFORMERS_CACHE/data/hf_cache/transformers export HF_HUB_OFFLINE1最后一行是给内网机器准备的。权重提前从有网的机器下载好、整目录拷进来之后把离线模式打开避免程序启动时还去联网检查更新卡在那里转圈。2.3 权重文件的完整性检查从外部拷贝权重最容易出的问题是文件不齐。模型目录里一般有config.json、modeling_*.py、tokenizer.model、若干*.safetensors分片还有一个*.index.json记录分片映射。拷贝中断会导致最后一个分片体积不对加载时报 safetensors 解析错误但报错信息往往指向别的地方很容易误判。我的检查习惯是两步先看分片数量和 index 文件里列的数量是否一致再逐个比对文件大小是否和源端一致。如果是用工具下载的注意下载工具的静默失败——看着进度条走完了实际缺一个文件。稳妥做法是下载完之后立刻跑一次“只加载 tokenizer”的测试这一步几乎不耗显存能快速确认目录结构对不对。from transformers import LlamaTokenizer tok LlamaTokenizer.from_pretrained(/data/models/cogvlm-chat-hf, trust_remote_codeTrue) print(len(tok), tok.convert_tokens_to_ids(|endoftext|))能正常打印出词表大小说明 tokenizer 这块没问题可以继续往下走。3. 从零把模型加载起来环境齐了权重到位了接下来是最激动人心也最容易翻车的一步把模型读进显存。这一节从最小可运行代码开始逐步加量化、加多卡最后给一个能直接抄的模板。3.1 半精度加载先跑通再优化第一版代码不要开量化不要开多卡就在能装得下的机器上用半精度跑一次。目的是确认模型本身没问题把变量降到最少。import torch from transformers import AutoModelForCausalLM, LlamaTokenizer MODEL_PATH /data/models/cogvlm-chat-hf tokenizer LlamaTokenizer.from_pretrained(MODEL_PATH, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( MODEL_PATH, torch_dtypetorch.bfloat16, low_cpu_mem_usageTrue, trust_remote_codeTrue, device_mapcuda:0, ).eval()几个参数值得解释。low_cpu_mem_usageTrue会分片加载权重避免先把整个模型读进内存再搬到显存对于内存不大比如 64G的机器这个开关是从“卡死”到“能跑”的区别。device_map这里我故意写死成cuda:0而不是auto原因后面讲多卡时会说到。加载完成后先用一段纯文本跑一次确认语言部分正常resp, _ model.chat(tokenizer, 用一句话说明什么是视觉语言模型, history[]) print(resp)这一步不涉及图像速度很快。如果这一步就出问题那多半是 tokenizer 或者模型文件的问题和视觉模块无关排查范围小很多。3.2 图像输入的正确喂法图像输入不是简单地把 PIL 对象传进去就完事。模型自带的build_conversation_input_ids会做一套预处理缩放、归一化、切成 patch然后把视觉 token 按模板拼进 prompt。你需要注意的是图像尺寸和格式。from PIL import Image image Image.open(/data/workspace/demo.png).convert(RGB) inputs model.build_conversation_input_ids( tokenizer, query这张图里有什么请详细描述。, history[], images[image], ) inputs {k: v.to(cuda:0).to(torch.bfloat16) if v.dtype torch.float32 else v.to(cuda:0) for k, v in inputs.items()} with torch.no_grad(): out model.generate(**inputs, max_new_tokens256, do_sampleFalse) print(tokenizer.decode(out[0][inputs[input_ids].shape[1]:], skip_special_tokensTrue))这里有个细节很多人忽略build_conversation_input_ids返回的是一个字典里面的images字段类型是float32的张量。如果你的模型是 bf16 精度这个张量也要转成 bf16否则会在视觉编码器里报 dtype 不匹配。上面那行推导式就是干这个的虽然写得有点丑但比在模型内部改代码安全。另一个细节是do_sampleFalse。做图像理解和 GUI 定位这类任务时我强烈建议用贪心解码也就是关掉采样。采样带来的多样性在这里是负面因素——同一个按钮两次运行给你两个不同坐标下游流程根本没法用。只有做开放式描述、创意类问答时才需要打开temperature。3.3 4bit 量化把大模型塞进小显存单卡 24G 是很多人的现实条件这时候 4bit 量化几乎是唯一选择。做法不复杂加一个量化配置对象就行import torch from transformers import AutoModelForCausalLM, LlamaTokenizer, BitsAndBytesConfig MODEL_PATH /data/models/cogvlm-chat-hf bnb_config BitsAndBytesConfig( load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypetorch.bfloat16, bnb_4bit_use_double_quantTrue, ) tokenizer LlamaTokenizer.from_pretrained(MODEL_PATH, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( MODEL_PATH, quantization_configbnb_config, torch_dtypetorch.bfloat16, low_cpu_mem_usageTrue, trust_remote_codeTrue, device_mapcuda:0, ).eval()nf4是正态分布友好的 4bit 数据类型比普通 int4 在这类模型上掉的精度少double_quant是对量化常数再做一次量化能再省一两个 G代价是加载稍微慢一点。compute_dtype一定要设成 bf16设成 fp16 在部分卡上会出现激活溢出输出变成一堆重复的字符或者直接 NaN。量化之后的实际体验在 24G 卡上跑 17B 模型留出 4G 左右给上下文对话轮次控制在 3 轮以内基本不会 OOM。速度方面生成一句话二三十个 token大概一两秒描述一张中等复杂度的图两百 token十几秒的量级。这个速度做批处理不算快做交互式工具完全够用。注意量化后模型对数字和精确坐标的敏感度会下降。做 GUI 定位时如果发现坐标明显漂移先试着回到半精度验证是不是量化导致的别一头扎进坐标换算里查半天。3.4 双卡切分与那些说不清的报错显存够但单卡装不下时第一反应是把device_map改成auto。这一步能成但成功率不高。原因在于这类模型的视觉专家模块是通过自定义逻辑插入的accelerate的自动切分策略不一定能正确识别这些层结果就是一部分权重被放到 cuda:1但计算时张量在 cuda:0报一个 device mismatch。我的处理顺序是这样的先试device_mapauto能跑就不管了报 device 错误就改成手工指定的字典把视觉相关的层固定在第一张卡上语言层往后排。手工字典写起来麻烦但可控。另一个办法是干脆用两张卡各跑一个模型实例前面挂个简单的调度做并发处理这在批处理场景下反而更简单粗暴有效。还有一个常见问题是双卡机器上的 NVLink 缺失。没有 NVLink 时跨卡通信走 PCIe速度会掉一截特别是层间频繁交换数据的结构。如果你的机器没有 NVLink别对双卡加速抱太大期望能跑通就行。4. CogAgent 的 GUI 能力怎么真正用起来CogVLM 的用法相对直白进去一张图出来一段字。CogAgent 的链路长得多截屏、预处理、构造 prompt、推理、解析动作、坐标换算、执行、再截屏形成一个闭环。任何一个环节没对齐整个链路就是错的而且很难从最终现象倒推是哪一环。4.1 分辨率与 letterbox 预处理高分辨率是 CogAgent 的核心卖点但“高分辨率”不等于“直接把原图丢进去”。模型有一个固定的输入尺寸通常是 1120 这个量级你的截图可能是 1920x1080也可能是 2560x1440直接 resize 会拉伸变形模型对按钮形状的判断会受影响。正确做法是等比缩放加填充也就是 letterbox。from PIL import Image def letterbox(img, target1120): w, h img.size scale min(target / w, target / h) nw, nh int(round(w * scale)), int(round(h * scale)) resized img.resize((nw, nh), Image.BICUBIC) canvas Image.new(RGB, (target, target), (0, 0, 0)) pad_x (target - nw) // 2 pad_y (target - nh) // 2 canvas.paste(resized, (pad_x, pad_y)) return canvas, scale, pad_x, pad_y函数返回的scale、pad_x、pad_y三个值要一路带着走后面坐标换算全靠它们。这里用 BICUBIC 而不是默认的 NEAREST是因为界面上的小字和细线条在 NEAREST 下会丢信息缩完以后模型读不出来。填充色用黑色0,0,0比较稳妥。有些实现用白色在某些浅色主题的界面上会和内容混在一起模型分不清边界。4.2 动作解析别信“模型会给你标准格式”模型输出的动作文本理想情况下是规整的一行比如“点击坐标 (x, y)”。实际跑起来你会发现它偶尔加一句解释、偶尔换个动词、偶尔把坐标写进括号里又跟一句补充说明。所以解析层必须写得宽容一些用正则去捞关键信息而不是拿字符串精确匹配。我一般的做法是先按行切找包含动作关键词的那一行再用正则提取动作类型和参数。动作类型做一层映射把同义词归到统一的枚举里比如“点击”“按”“点一下”统一成 CLICK。坐标提取用\(?\s*(\d)\s*[,]\s*(\d)\s*\)?这种宽松模式中英文逗号都要考虑。解析失败时不要直接抛异常让流程中断应该记录原始输出、记录当时的截图然后走一个兜底分支。这个日志在调 prompt 的时候价值极高你能看到模型到底在哪一步“想偏了”。4.3 坐标换算与标定这是整个链路里最容易出错的地方。模型输出的坐标是在 1120 空间里的你要换成真实屏幕坐标公式是def to_screen(x_model, y_model, scale, pad_x, pad_y): x (x_model - pad_x) / scale y (y_model - pad_y) / scale return int(round(x)), int(round(y))看起来很简单但有两个陷阱。第一有些模型的输出坐标已经内部还原到原图了你再还原一次就错得离谱。第二缩放用的是min而不是等比拉伸如果原图不是正方形横纵比例其实是一致的但填充偏移只在某一个方向上有。判断到底是哪种情况靠标定。截一张图上面画几个位置已知的标记让模型去找其中一个看输出的数值落在哪个区间。如果数值都在 0 到 1120 之间那就是缩放空间如果数值接近原图宽高那就是已经还原过。这个测试做一次后面就不用反复猜了。实操心得标定的时候多用几个不同位置的元素比如左上角、右下角、正中心各一个。如果中心点准而边角偏说明是填充偏移没减对如果整体线性偏移说明缩放比算错了如果只有某个方向偏检查一下是不是宽高搞反了。5. 踩坑实录与排查速查表这一节把我实际遇到的和同行反馈过的问题整理成表按现象倒查原因。这类问题的特点是报错信息经常“文不对题”看报错猜原因大概率猜错还是按现象查比较快。5.1 加载阶段的问题现象大概率原因处理方式KeyError: xxx出现在 config 解析处transformers版本过新或过旧回退到 4.37 到 4.42 区间AttributeError: module has no attribute _supports_sdpa版本不匹配的典型表现同上锁版本而非改代码safetensors解析失败权重分片不完整核对分片数量与 index 文件CUDA out of memory在加载时未开low_cpu_mem_usage加上该参数并考虑量化卡在Loading checkpoint shards很久磁盘 IO 瓶颈或内存不足换数据盘检查 swap 是否被疯狂使用No module named xxx模型自带代码依赖了没装的包看报错补装注意版本别太新加载阶段的问题九成能靠“锁版本 查文件完整性”解决。我遇到过最诡异的一次是 safetensors 报错查了半天发现是拷贝过程中磁盘满了最后一个分片被截断。这种问题报错信息完全不指向磁盘只能靠比对文件大小发现。5.2 推理阶段的问题推理阶段的现象更隐蔽因为程序不报错只是结果不对。输出全是重复字符或者乱码。第一反应是量化精度问题特别是compute_dtype设成了 fp16 的情况。改成 bf16 通常就好。如果没开量化也这样检查一下是不是max_new_tokens设得太大配合了错误的eos_token_id模型不知道什么时候停。答非所问或者把图片内容完全说错。先确认图像张量的 dtype 和 device 都对。我踩过一次图像张量留在了 CPU 上模型居然没报错只是把图像当成全黑处理输出了一段完全不相干的描述。这种“静默失败”最坑所以加载完之后一定要打印一下输入张量的 shape、dtype 和 device 做核对。生成到一半卡住不动。多半是显存临界系统在做内存和显存之间的交换。把max_new_tokens降下来或者减少历史轮次。多轮对话越跑越慢。KV Cache 在累积。这类模型每轮都要重新处理历史长对话下显存和耗时都是线性增长的。做批处理时我一般每张图开一个全新会话不共享历史反而更快更稳。5.3 GUI 定位专项问题GUI 场景的问题和通用理解不太一样单独拎出来说。坐标系统性偏移。大概率是 letterbox 参数没跟上。检查缩放比是用min算的还是用宽高分别算的填充偏移有没有在不同分辨率下重新计算。我见过一个实现把pad_x、pad_y写成了全局常量换一台显示器就全错。模型说“找不到该元素”。先看截图里那个元素是不是太小或者对比度太低。高分辨率输入的意义就在这如果元素在缩放后只有几个像素模型确实看不见。解决办法是局部截图——先把屏幕分成几块逐块送进去找找到了再在原图里换算。这个策略在复杂界面上比整屏一次送入准确得多。动作类型判断错误。比如该点击的它说要输入。这种情况多半是 prompt 描述得不够明确。把当前界面的上下文、上一步做了什么、目标是什么写清楚准确率会明显上升。GUI 任务对 prompt 的敏感度远高于通用问答。连续两步动作互相矛盾。因为每一步都是独立推理模型没有记忆。要么把历史动作拼进 prompt要么在外部加一层状态机做约束。我倾向于后者状态机逻辑清晰、可控模型只负责“看”决策交给代码。6. 让它跑得更好几个真正有效的调优点模型能跑起来只是及格线实际用起来你会发现效果差异很大而差异的来源往往不是模型本身是输入的组织方式。6.1 prompt 的组织方式视觉语言模型对 prompt 的敏感度比纯文本模型高因为图像信息和文本信息要在同一个上下文里对齐。几条我验证过有效的经验提问要具体不要说“描述这张图”要说“图中表格第三行第二列的内容是什么”。前者模型会给你一段泛泛而谈后者能直接命中你要的信息。需要结构化输出时在 prompt 里给格式示例比事后用正则去捞要可靠得多。比如你要 JSON就在 prompt 里写一个 JSON 骨架模型会照着填。中文和英文混着用一般没问题但涉及界面元素名称时用界面上实际显示的语言更准。界面上写的是英文按钮你问“那个蓝色的确认按钮在哪”不如问“Where is the Submit button”。做 OCR 类任务时明确告诉模型“只输出识别到的文字不要解释”能省掉大量后处理。6.2 推理参数的取舍参数不多但每个都影响结果参数通用理解任务GUI 定位任务说明do_sample可开可关必须关采样会引入不确定性temperature0.2 到 0.7不适用关闭采样后此参数失效max_new_tokens256 到 51264 到 128定位类输出很短设大了浪费repetition_penalty1.0 到 1.11.0过高会让输出变得生硬num_beams11束搜索在这类任务上收益很低GUI 任务里我把max_new_tokens压到 128 甚至 64效果反而是提升的。原因很简单输出空间被限制后模型没有余地在那里“思考人生”必须尽快给出动作。这是个很实用的小技巧。6.3 批处理与吞吐如果要做批量图片理解逐张串行跑会非常慢。可行的加速方式有几个层次第一层是把多张图拼成一个 batch 送进去。这类模型对 batch 的支持要看具体实现有的版本在build_conversation_input_ids层面就只支持单图硬拼会出错得自己改预处理逻辑。改动有风险建议先在小样本上验证结果一致性。第二层是起多个进程每个进程占一张卡或者共享一张卡的不同显存段。简单粗暴但有效尤其是处理几千张图的离线任务多进程的收益比任何模型层面的优化都直接。第三层是推理框架。有些通用推理加速框架对这类自定义结构的支持有限需要额外的适配工作投入产出比要先算清楚。如果只是自己用多进程加 4bit 量化基本够如果要上生产那值得花时间做专门的适配。提示批处理时务必给每张图记录完整的输入参数和输出原文。模型偶尔会在某张图上抽风没有日志你根本不知道是哪张、为什么。我习惯把原图、prompt、原始输出、解析后的结果四样一起落盘出问题直接翻记录。7. 我在这套流程里攒下的几点体会第一点关于显存。别一上来就追求半精度跑满血版本量化带来的精度损失在大多数任务里感知不到但省下来的显存能让你把上下文拉长、把 batch 开大综合体验反而更好。真正需要半精度的场景是坐标精度要求极高的 GUI 定位和细小文字的 OCR这两种情况我才会回到 bf16 并接受更慢的速度。第二点关于版本。这类模型的自定义代码是把双刃剑它让模型能做很多标准架构做不到的事也让部署变得脆弱。我的做法是每个项目建一个独立环境并冻结依赖宁可磁盘多占几个 G也不要让两个项目共用一个环境互相打架。这个习惯救过我很多次。第三点关于坐标。GUI 相关的坑九成能在标定这一步提前发现。别嫌麻烦画几个标记点测一次把缩放比和偏移量打印出来肉眼确认数值合理再往下接自动化。我见过太多人跳过这一步然后在“为什么点不准”上耗掉一整天。最后分享一个排查思路。当模型输出明显不对时先别改 prompt、别调参数先把输入可视化出来看一眼——图像有没有变形、有没有被裁掉、颜色通道对不对、张量在不在正确的设备上。我遇到过的“模型不行”里至少一半最后发现是输入喂错了。把输入管好剩下的问题才好谈。
1. 先把这两个模型能干什么弄清楚再谈怎么跑想把 CogVLM 与 CogAgent 部署到本地最容易踩的第一个坑是以为它们是同一类东西装个环境就能一起用。实际情况差得挺远CogVLM 是通用的视觉语言模型你给它一张图加一句话它给你一段描述、一段分析或者一段 OCR 结果CogAgent 是在前者的底座上继续往 GUI 方向训练出来的智能体模型它看的是截图输出的是“点哪里、输入什么、往下滚多少”这类动作指令。部署 CogVLM 的流程和部署 CogAgent 的流程九成相似但剩下那一成——输入分辨率、prompt 模板、坐标换算——决定了你能不能真正跑起来。我前后在两台机器上折腾了差不多一周第一台是单卡 24G 的消费级卡第二台是双卡 48G 的工作站中间踩的坑基本都集中在显存、依赖版本和坐标映射这三处所以下面按这三条主线展开。先说清楚“本地部署”这件事的价值。很多人第一反应是调接口不就完了何必自己折腾显存和依赖。但实际项目里需要本地跑的场景非常硬内网隔离的机器没有外网、每天要处理几万张截图不能按次计费、需要对模型输出做自由的后处理、需要把模型嵌进已有的自动化流程里当一个小模块用。这些需求叠在一起本地部署就成了唯一解。而 CogVLM 这类模型的好处在于它的权重和推理代码都是开放的你能看到视觉专家模块怎么接进去、图像怎么预处理、tokenizer 怎么拼 prompt这些细节在调效果的时候全是关键。1.1 CogVLM看图说话的通用底座CogVLM 的结构可以拆成三块来理解一块视觉编码器负责把图片变成特征一块语言模型负责生成文字中间还有一个“视觉专家”模块专门在语言模型的若干层里插入可训练的视觉通路。打个比方语言模型是一条跑了很久的高速公路视觉专家相当于在关键路口修了几条匝道让图像信息能就近汇入而不是全部挤在入口处硬塞进去。这个设计带来的直接好处是模型对图像细节的敏感度比“把图像特征拼在 prompt 前面”那种朴素做法要好不少尤其是小字、表格、界面元素这类需要精确读取的内容。对部署者来说这个结构意味着两件事。第一模型总参数量比同级别的纯文本模型大权重占用的显存更多17B 级别的模型在半精度下光权重就要 34GB 上下单卡 24G 根本放不下必须走量化或者多卡。第二它依赖trust_remote_codeTrue加载自定义代码也就是说模型目录里自带建模文件这些文件对transformers的版本相当挑剔版本差一点就可能报出一堆看着莫名其妙的错。后面我会具体说版本怎么选。1.2 CogAgent盯着屏幕找按钮的那一类CogAgent 的定位更垂直。它的输入是一张屏幕截图输出是结构化的动作比如点击某个坐标、在某个位置输入文本、滚动页面。它的图像输入分辨率比通用版更高因为 GUI 界面上的按钮、输入框、图标都很小压缩得太狠模型就看不见了。高分辨率带来的代价是显存和计算量同步上升同样一张图编码出来的视觉 token 数量可能是普通图片的好几倍。部署 CogAgent 时最需要提前想清楚的是坐标系问题。模型是在缩放后的图像上做定位的而你的真实屏幕是原始分辨率两者之间差一个缩放比和一个可能的填充偏移。这个换算如果做错模型明明“看对了”点下去却偏了半个屏幕排查起来非常折磨人。我建议在正式接入自动化流程之前先做一次坐标标定用几个已知位置的元素验证映射关系这一步花十分钟能省掉后面几小时的怀疑人生。1.3 什么配置的机器能跑先说结论很多人卡在第一步不知道自己手上的机器够不够。我把几种常见配置的实际情况列出来方便你对照。注意这里说的是“能跑起来并输出合理结果”不是“能跑得飞快”。模型规模精度权重显存加上激活与KV后的实际占用建议硬件17B 级别bf16约 34GB38GB 到 42GB单卡 48G 或双卡 24G17B 级别4bit 量化约 10GB13GB 到 16GB单卡 24G 可用19B 级别bf16约 38GB42GB 到 46GB单卡 48G双卡更稳19B 级别4bit 量化约 11GB14GB 到 18GB单卡 24G 可跑18B 级别GUI 版4bit 量化约 11GB15GB 到 19GB单卡 24G高分辨率截图更吃显存这张表里的“实际占用”不是拍脑袋后面会给出估算方法。简单说权重只是地基真正把显存撑爆的往往是长 prompt 的 KV Cache 和高分辨率图像产生的视觉 token。一张 1120 见方的截图编码出来的 token 数量可能顶得上几百个中文字做多轮对话时这部分会持续累积。2. 环境这一关版本对齐比装包重要得多我先说一个反直觉的结论这类模型的部署失败八成不是硬件不够是版本不对。你按某个教程装了一套包代码跑起来报AttributeError或者KeyError搜半天发现是transformers小版本差了两位。这种问题没有通用解只能靠锁定版本。我的做法是先在一个干净环境里装最小依赖集跑通官方示例再往里面加东西一旦加出问题立刻回退绝不在一棵已经长歪的树上继续嫁接。2.1 依赖版本的三角关系需要同时对齐的有三样CUDA 驱动、PyTorch、transformers。三者是链式依赖任何一环错位都会在加载模型时炸出来。CUDA 与 PyTorch先看nvidia-smi右上角显示的驱动支持的最高 CUDA 版本然后选一个不高于它的 PyTorch 轮子。驱动支持 12.1你装 cu121 的轮子最省事硬装 cu118 的轮子通常也能跑但要留意量化库有没有对应编译版本。PyTorch 与transformers这一对最容易出事。模型自带的建模代码里会 import 一些内部类新版transformers改了签名就会直接报错。量化库4bit 加载依赖bitsandbytes它需要和 CUDA 运行时匹配版本太旧会报找不到符号。我实测下来比较稳的一组是PyTorch 2.1 到 2.3 区间transformers4.37 到 4.42 区间accelerate0.26 以上bitsandbytes0.41 以上。这个组合不是唯一解但它是个“大多数教程和模型自带代码都能兼容”的安全区。如果你拿到的是更新的模型版本可以适当往上走但务必先用最小脚本验证加载别一上来就跑完整业务。提示不要用pip install -U无脑升级。跑通之后立刻pip freeze requirements.lock把当前环境冻住这是血泪教训。我有一次为了装另一个库顺手升了transformers第二天回来模型加载直接崩回滚花了半小时。2.2 隔离环境与目录规划不要往系统 Python 里装东西这是底线。用 conda 或者 venv 建一个独立环境名字起得直白点比如vlm-local。模型权重体积大一般十几个到几十个 G别放在系统盘找个数据盘建个统一目录mkdir -p /data/models/cogvlm-chat-hf mkdir -p /data/models/cogagent-chat-hf mkdir -p /data/workspace/vlm-demo权重放/data/models下代码放/data/workspace下缓存目录也要单独指出来否则 HuggingFace 默认会往家目录的隐藏文件夹里塞跑几个模型下来把根分区撑满是常有的事。环境变量这样设export HF_HOME/data/hf_cache export TRANSFORMERS_CACHE/data/hf_cache/transformers export HF_HUB_OFFLINE1最后一行是给内网机器准备的。权重提前从有网的机器下载好、整目录拷进来之后把离线模式打开避免程序启动时还去联网检查更新卡在那里转圈。2.3 权重文件的完整性检查从外部拷贝权重最容易出的问题是文件不齐。模型目录里一般有config.json、modeling_*.py、tokenizer.model、若干*.safetensors分片还有一个*.index.json记录分片映射。拷贝中断会导致最后一个分片体积不对加载时报 safetensors 解析错误但报错信息往往指向别的地方很容易误判。我的检查习惯是两步先看分片数量和 index 文件里列的数量是否一致再逐个比对文件大小是否和源端一致。如果是用工具下载的注意下载工具的静默失败——看着进度条走完了实际缺一个文件。稳妥做法是下载完之后立刻跑一次“只加载 tokenizer”的测试这一步几乎不耗显存能快速确认目录结构对不对。from transformers import LlamaTokenizer tok LlamaTokenizer.from_pretrained(/data/models/cogvlm-chat-hf, trust_remote_codeTrue) print(len(tok), tok.convert_tokens_to_ids(|endoftext|))能正常打印出词表大小说明 tokenizer 这块没问题可以继续往下走。3. 从零把模型加载起来环境齐了权重到位了接下来是最激动人心也最容易翻车的一步把模型读进显存。这一节从最小可运行代码开始逐步加量化、加多卡最后给一个能直接抄的模板。3.1 半精度加载先跑通再优化第一版代码不要开量化不要开多卡就在能装得下的机器上用半精度跑一次。目的是确认模型本身没问题把变量降到最少。import torch from transformers import AutoModelForCausalLM, LlamaTokenizer MODEL_PATH /data/models/cogvlm-chat-hf tokenizer LlamaTokenizer.from_pretrained(MODEL_PATH, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( MODEL_PATH, torch_dtypetorch.bfloat16, low_cpu_mem_usageTrue, trust_remote_codeTrue, device_mapcuda:0, ).eval()几个参数值得解释。low_cpu_mem_usageTrue会分片加载权重避免先把整个模型读进内存再搬到显存对于内存不大比如 64G的机器这个开关是从“卡死”到“能跑”的区别。device_map这里我故意写死成cuda:0而不是auto原因后面讲多卡时会说到。加载完成后先用一段纯文本跑一次确认语言部分正常resp, _ model.chat(tokenizer, 用一句话说明什么是视觉语言模型, history[]) print(resp)这一步不涉及图像速度很快。如果这一步就出问题那多半是 tokenizer 或者模型文件的问题和视觉模块无关排查范围小很多。3.2 图像输入的正确喂法图像输入不是简单地把 PIL 对象传进去就完事。模型自带的build_conversation_input_ids会做一套预处理缩放、归一化、切成 patch然后把视觉 token 按模板拼进 prompt。你需要注意的是图像尺寸和格式。from PIL import Image image Image.open(/data/workspace/demo.png).convert(RGB) inputs model.build_conversation_input_ids( tokenizer, query这张图里有什么请详细描述。, history[], images[image], ) inputs {k: v.to(cuda:0).to(torch.bfloat16) if v.dtype torch.float32 else v.to(cuda:0) for k, v in inputs.items()} with torch.no_grad(): out model.generate(**inputs, max_new_tokens256, do_sampleFalse) print(tokenizer.decode(out[0][inputs[input_ids].shape[1]:], skip_special_tokensTrue))这里有个细节很多人忽略build_conversation_input_ids返回的是一个字典里面的images字段类型是float32的张量。如果你的模型是 bf16 精度这个张量也要转成 bf16否则会在视觉编码器里报 dtype 不匹配。上面那行推导式就是干这个的虽然写得有点丑但比在模型内部改代码安全。另一个细节是do_sampleFalse。做图像理解和 GUI 定位这类任务时我强烈建议用贪心解码也就是关掉采样。采样带来的多样性在这里是负面因素——同一个按钮两次运行给你两个不同坐标下游流程根本没法用。只有做开放式描述、创意类问答时才需要打开temperature。3.3 4bit 量化把大模型塞进小显存单卡 24G 是很多人的现实条件这时候 4bit 量化几乎是唯一选择。做法不复杂加一个量化配置对象就行import torch from transformers import AutoModelForCausalLM, LlamaTokenizer, BitsAndBytesConfig MODEL_PATH /data/models/cogvlm-chat-hf bnb_config BitsAndBytesConfig( load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypetorch.bfloat16, bnb_4bit_use_double_quantTrue, ) tokenizer LlamaTokenizer.from_pretrained(MODEL_PATH, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( MODEL_PATH, quantization_configbnb_config, torch_dtypetorch.bfloat16, low_cpu_mem_usageTrue, trust_remote_codeTrue, device_mapcuda:0, ).eval()nf4是正态分布友好的 4bit 数据类型比普通 int4 在这类模型上掉的精度少double_quant是对量化常数再做一次量化能再省一两个 G代价是加载稍微慢一点。compute_dtype一定要设成 bf16设成 fp16 在部分卡上会出现激活溢出输出变成一堆重复的字符或者直接 NaN。量化之后的实际体验在 24G 卡上跑 17B 模型留出 4G 左右给上下文对话轮次控制在 3 轮以内基本不会 OOM。速度方面生成一句话二三十个 token大概一两秒描述一张中等复杂度的图两百 token十几秒的量级。这个速度做批处理不算快做交互式工具完全够用。注意量化后模型对数字和精确坐标的敏感度会下降。做 GUI 定位时如果发现坐标明显漂移先试着回到半精度验证是不是量化导致的别一头扎进坐标换算里查半天。3.4 双卡切分与那些说不清的报错显存够但单卡装不下时第一反应是把device_map改成auto。这一步能成但成功率不高。原因在于这类模型的视觉专家模块是通过自定义逻辑插入的accelerate的自动切分策略不一定能正确识别这些层结果就是一部分权重被放到 cuda:1但计算时张量在 cuda:0报一个 device mismatch。我的处理顺序是这样的先试device_mapauto能跑就不管了报 device 错误就改成手工指定的字典把视觉相关的层固定在第一张卡上语言层往后排。手工字典写起来麻烦但可控。另一个办法是干脆用两张卡各跑一个模型实例前面挂个简单的调度做并发处理这在批处理场景下反而更简单粗暴有效。还有一个常见问题是双卡机器上的 NVLink 缺失。没有 NVLink 时跨卡通信走 PCIe速度会掉一截特别是层间频繁交换数据的结构。如果你的机器没有 NVLink别对双卡加速抱太大期望能跑通就行。4. CogAgent 的 GUI 能力怎么真正用起来CogVLM 的用法相对直白进去一张图出来一段字。CogAgent 的链路长得多截屏、预处理、构造 prompt、推理、解析动作、坐标换算、执行、再截屏形成一个闭环。任何一个环节没对齐整个链路就是错的而且很难从最终现象倒推是哪一环。4.1 分辨率与 letterbox 预处理高分辨率是 CogAgent 的核心卖点但“高分辨率”不等于“直接把原图丢进去”。模型有一个固定的输入尺寸通常是 1120 这个量级你的截图可能是 1920x1080也可能是 2560x1440直接 resize 会拉伸变形模型对按钮形状的判断会受影响。正确做法是等比缩放加填充也就是 letterbox。from PIL import Image def letterbox(img, target1120): w, h img.size scale min(target / w, target / h) nw, nh int(round(w * scale)), int(round(h * scale)) resized img.resize((nw, nh), Image.BICUBIC) canvas Image.new(RGB, (target, target), (0, 0, 0)) pad_x (target - nw) // 2 pad_y (target - nh) // 2 canvas.paste(resized, (pad_x, pad_y)) return canvas, scale, pad_x, pad_y函数返回的scale、pad_x、pad_y三个值要一路带着走后面坐标换算全靠它们。这里用 BICUBIC 而不是默认的 NEAREST是因为界面上的小字和细线条在 NEAREST 下会丢信息缩完以后模型读不出来。填充色用黑色0,0,0比较稳妥。有些实现用白色在某些浅色主题的界面上会和内容混在一起模型分不清边界。4.2 动作解析别信“模型会给你标准格式”模型输出的动作文本理想情况下是规整的一行比如“点击坐标 (x, y)”。实际跑起来你会发现它偶尔加一句解释、偶尔换个动词、偶尔把坐标写进括号里又跟一句补充说明。所以解析层必须写得宽容一些用正则去捞关键信息而不是拿字符串精确匹配。我一般的做法是先按行切找包含动作关键词的那一行再用正则提取动作类型和参数。动作类型做一层映射把同义词归到统一的枚举里比如“点击”“按”“点一下”统一成 CLICK。坐标提取用\(?\s*(\d)\s*[,]\s*(\d)\s*\)?这种宽松模式中英文逗号都要考虑。解析失败时不要直接抛异常让流程中断应该记录原始输出、记录当时的截图然后走一个兜底分支。这个日志在调 prompt 的时候价值极高你能看到模型到底在哪一步“想偏了”。4.3 坐标换算与标定这是整个链路里最容易出错的地方。模型输出的坐标是在 1120 空间里的你要换成真实屏幕坐标公式是def to_screen(x_model, y_model, scale, pad_x, pad_y): x (x_model - pad_x) / scale y (y_model - pad_y) / scale return int(round(x)), int(round(y))看起来很简单但有两个陷阱。第一有些模型的输出坐标已经内部还原到原图了你再还原一次就错得离谱。第二缩放用的是min而不是等比拉伸如果原图不是正方形横纵比例其实是一致的但填充偏移只在某一个方向上有。判断到底是哪种情况靠标定。截一张图上面画几个位置已知的标记让模型去找其中一个看输出的数值落在哪个区间。如果数值都在 0 到 1120 之间那就是缩放空间如果数值接近原图宽高那就是已经还原过。这个测试做一次后面就不用反复猜了。实操心得标定的时候多用几个不同位置的元素比如左上角、右下角、正中心各一个。如果中心点准而边角偏说明是填充偏移没减对如果整体线性偏移说明缩放比算错了如果只有某个方向偏检查一下是不是宽高搞反了。5. 踩坑实录与排查速查表这一节把我实际遇到的和同行反馈过的问题整理成表按现象倒查原因。这类问题的特点是报错信息经常“文不对题”看报错猜原因大概率猜错还是按现象查比较快。5.1 加载阶段的问题现象大概率原因处理方式KeyError: xxx出现在 config 解析处transformers版本过新或过旧回退到 4.37 到 4.42 区间AttributeError: module has no attribute _supports_sdpa版本不匹配的典型表现同上锁版本而非改代码safetensors解析失败权重分片不完整核对分片数量与 index 文件CUDA out of memory在加载时未开low_cpu_mem_usage加上该参数并考虑量化卡在Loading checkpoint shards很久磁盘 IO 瓶颈或内存不足换数据盘检查 swap 是否被疯狂使用No module named xxx模型自带代码依赖了没装的包看报错补装注意版本别太新加载阶段的问题九成能靠“锁版本 查文件完整性”解决。我遇到过最诡异的一次是 safetensors 报错查了半天发现是拷贝过程中磁盘满了最后一个分片被截断。这种问题报错信息完全不指向磁盘只能靠比对文件大小发现。5.2 推理阶段的问题推理阶段的现象更隐蔽因为程序不报错只是结果不对。输出全是重复字符或者乱码。第一反应是量化精度问题特别是compute_dtype设成了 fp16 的情况。改成 bf16 通常就好。如果没开量化也这样检查一下是不是max_new_tokens设得太大配合了错误的eos_token_id模型不知道什么时候停。答非所问或者把图片内容完全说错。先确认图像张量的 dtype 和 device 都对。我踩过一次图像张量留在了 CPU 上模型居然没报错只是把图像当成全黑处理输出了一段完全不相干的描述。这种“静默失败”最坑所以加载完之后一定要打印一下输入张量的 shape、dtype 和 device 做核对。生成到一半卡住不动。多半是显存临界系统在做内存和显存之间的交换。把max_new_tokens降下来或者减少历史轮次。多轮对话越跑越慢。KV Cache 在累积。这类模型每轮都要重新处理历史长对话下显存和耗时都是线性增长的。做批处理时我一般每张图开一个全新会话不共享历史反而更快更稳。5.3 GUI 定位专项问题GUI 场景的问题和通用理解不太一样单独拎出来说。坐标系统性偏移。大概率是 letterbox 参数没跟上。检查缩放比是用min算的还是用宽高分别算的填充偏移有没有在不同分辨率下重新计算。我见过一个实现把pad_x、pad_y写成了全局常量换一台显示器就全错。模型说“找不到该元素”。先看截图里那个元素是不是太小或者对比度太低。高分辨率输入的意义就在这如果元素在缩放后只有几个像素模型确实看不见。解决办法是局部截图——先把屏幕分成几块逐块送进去找找到了再在原图里换算。这个策略在复杂界面上比整屏一次送入准确得多。动作类型判断错误。比如该点击的它说要输入。这种情况多半是 prompt 描述得不够明确。把当前界面的上下文、上一步做了什么、目标是什么写清楚准确率会明显上升。GUI 任务对 prompt 的敏感度远高于通用问答。连续两步动作互相矛盾。因为每一步都是独立推理模型没有记忆。要么把历史动作拼进 prompt要么在外部加一层状态机做约束。我倾向于后者状态机逻辑清晰、可控模型只负责“看”决策交给代码。6. 让它跑得更好几个真正有效的调优点模型能跑起来只是及格线实际用起来你会发现效果差异很大而差异的来源往往不是模型本身是输入的组织方式。6.1 prompt 的组织方式视觉语言模型对 prompt 的敏感度比纯文本模型高因为图像信息和文本信息要在同一个上下文里对齐。几条我验证过有效的经验提问要具体不要说“描述这张图”要说“图中表格第三行第二列的内容是什么”。前者模型会给你一段泛泛而谈后者能直接命中你要的信息。需要结构化输出时在 prompt 里给格式示例比事后用正则去捞要可靠得多。比如你要 JSON就在 prompt 里写一个 JSON 骨架模型会照着填。中文和英文混着用一般没问题但涉及界面元素名称时用界面上实际显示的语言更准。界面上写的是英文按钮你问“那个蓝色的确认按钮在哪”不如问“Where is the Submit button”。做 OCR 类任务时明确告诉模型“只输出识别到的文字不要解释”能省掉大量后处理。6.2 推理参数的取舍参数不多但每个都影响结果参数通用理解任务GUI 定位任务说明do_sample可开可关必须关采样会引入不确定性temperature0.2 到 0.7不适用关闭采样后此参数失效max_new_tokens256 到 51264 到 128定位类输出很短设大了浪费repetition_penalty1.0 到 1.11.0过高会让输出变得生硬num_beams11束搜索在这类任务上收益很低GUI 任务里我把max_new_tokens压到 128 甚至 64效果反而是提升的。原因很简单输出空间被限制后模型没有余地在那里“思考人生”必须尽快给出动作。这是个很实用的小技巧。6.3 批处理与吞吐如果要做批量图片理解逐张串行跑会非常慢。可行的加速方式有几个层次第一层是把多张图拼成一个 batch 送进去。这类模型对 batch 的支持要看具体实现有的版本在build_conversation_input_ids层面就只支持单图硬拼会出错得自己改预处理逻辑。改动有风险建议先在小样本上验证结果一致性。第二层是起多个进程每个进程占一张卡或者共享一张卡的不同显存段。简单粗暴但有效尤其是处理几千张图的离线任务多进程的收益比任何模型层面的优化都直接。第三层是推理框架。有些通用推理加速框架对这类自定义结构的支持有限需要额外的适配工作投入产出比要先算清楚。如果只是自己用多进程加 4bit 量化基本够如果要上生产那值得花时间做专门的适配。提示批处理时务必给每张图记录完整的输入参数和输出原文。模型偶尔会在某张图上抽风没有日志你根本不知道是哪张、为什么。我习惯把原图、prompt、原始输出、解析后的结果四样一起落盘出问题直接翻记录。7. 我在这套流程里攒下的几点体会第一点关于显存。别一上来就追求半精度跑满血版本量化带来的精度损失在大多数任务里感知不到但省下来的显存能让你把上下文拉长、把 batch 开大综合体验反而更好。真正需要半精度的场景是坐标精度要求极高的 GUI 定位和细小文字的 OCR这两种情况我才会回到 bf16 并接受更慢的速度。第二点关于版本。这类模型的自定义代码是把双刃剑它让模型能做很多标准架构做不到的事也让部署变得脆弱。我的做法是每个项目建一个独立环境并冻结依赖宁可磁盘多占几个 G也不要让两个项目共用一个环境互相打架。这个习惯救过我很多次。第三点关于坐标。GUI 相关的坑九成能在标定这一步提前发现。别嫌麻烦画几个标记点测一次把缩放比和偏移量打印出来肉眼确认数值合理再往下接自动化。我见过太多人跳过这一步然后在“为什么点不准”上耗掉一整天。最后分享一个排查思路。当模型输出明显不对时先别改 prompt、别调参数先把输入可视化出来看一眼——图像有没有变形、有没有被裁掉、颜色通道对不对、张量在不在正确的设备上。我遇到过的“模型不行”里至少一半最后发现是输入喂错了。把输入管好剩下的问题才好谈。
