DeepSeek Harness 已经接上了另一个模型,文字问答正常,图片也出现在会话里。但你问“这张图里有什么”,模型却回答无法查看附件,或者只复述图片文件名。
这类现象很容易被误判为模型效果差。实际上,图片可能停留在会话存储层,没有作为图像输入进入本次模型请求;也可能已经发出,却被 API 通道拒绝。
“会话里有图片”“请求里带图片”“模型支持看图”,是三个需要分别确认的事实。
对于正在搜索“DeepSeek Harness 接入其他模型”的开发者,文字调用成功只是起点。接入 GPT、Claude、Gemini、GLM 或其他模型的视觉版本,还需要确认输入能力声明、请求载荷和实际接口协议。本文按症状定位这三个边界,避免反复更换 Key,却始终没有检查到真正的问题。
技术资料核验日期为 2026 年 11 月 20 日。下文涉及 Harness 官方仓库当前文档,配置应与实际安装版本核对;示例模型名称和地址均为占位,不代表某款模型已在指定通道上线。
先按症状分流,三个问题不要一起改
下面的表可以作为第一轮排查记录。它说明优先检查的位置,不是仅凭一条报错就确定根因。
| 你看到的现象 | 优先检查 | 有帮助的对照 |
|---|---|---|
| 文字正常,一加图就被客户端拒绝 | 当前模型的图像输入声明 | 同一路由下的模型 input 或 inputModalities |
| 图片显示正常,回答却只有文件名或占位说明 | 本次模型请求是否实际包含图像 | 新会话、单图、同一视觉模型 |
| 单图可用,多轮后失败或旧图看不到 | 保留图片数量与编码后的载荷 | 一张图与多张图的请求体积 |
| 独立图片 API 可用,Harness 内仍失败 | 适配器、协议及内容转换 | 两条路径的模型 ID、端点和图片表示方式 |
如果连文字都无法调用,应先处理模型配置与请求失败问题。如果还没有接入其他模型,可以先完成API 中转配置与基础验收。当前这篇只处理已经进入图片输入阶段的问题。
边界一:写上模型名字,并没有声明它会看图
API 网关的模型目录回答的是“有哪些模型可供调用”。Harness 还需要知道当前模型允许接收哪些输入。
在官方的 Provider 配置指南中,pi-ai 路线使用模型级 input 字段;直接 DeepSeek 适配器使用 inputModalities。两者属于不同配置结构,不能把字段名称混用。GitHub
假设你正在通过 pi-ai 接入一个确认支持图片的 OpenAI Chat Completions 兼容通道,可以参考下面的片段:
- id: llm-pi-ai
config:
providers:
vision-gateway:
apiKeyEnv: MODEL_API_KEY
api: openai-completions
baseURL: https://gateway.example/v1
models:
- id: exact-vision-model-id
input: [text, image]这是一段 Profile patch 配置示例。MODEL_API_KEY 是凭证引用,实际密钥不要写在文章示例或共享配置里。地址和模型 ID 必须替换成当前账号真实可用的值。编辑已有 cordis.patch.yml 时,应保留其他 Provider 和必要字段,不要用这段示例覆盖完整配置。
input: [text, image] 的作用是声明能力,不会把纯文本模型变成视觉模型,也不会验证网关真的支持图片。声明与服务不一致时,请求仍可能在上游失败。
对于手动添加且目录没有描述的模型,pi-ai 的默认输入类型是文本。相关回退规则可以核对官方配置源码。因此,“模型名字里有 vision,但客户端没有自动识别”并不矛盾。
选择模型时也要落实到具体版本。不要把品牌名称、推理档位或价格高低当作图像能力说明。站内的 DeepSeek Pro 与 Flash 图片 API 选择文章讨论了这一判断方法;具体支持情况仍以当前官方文档和所选通道为准。
边界二:图片留在历史中,不代表每次都传原图
假设前几轮使用视觉模型,后来为了处理文字切换到纯文本模型。界面仍然保留原来的图片,属于正常的会话展示;当前请求如何表示这些图片,则由运行时和适配器决定。
pi-ai 适配器文档说明,切换到文本模型时,共享 LLM 运行时可以将图片引用投影为稳定的文字说明,持久历史仍保留图像引用。这种说明不是图片像素本身。GitHub
因此,模型准确复述文件名,不能证明它看到了图像。即使回答了图片内容,也可能沿用了上一轮的文字分析。排查时应使用一张新图片,避免历史答案干扰判断。
还需要区分手动上传的图片与历史会话导入的附件。如果问题发生在导入之后,先检查历史会话导入的附件恢复边界。一条图片卡片记录不一定携带可继续使用的原始图像。
为什么前几轮正常,后来才开始失败
多轮会话可能保留多张图片供后续请求使用。控制数量只是一个条件,编码后的字节数也是条件。
当前 pi-ai 配置中,有几组容易混淆的默认值:
| 参数 | 文档中的默认值 | 控制的对象 |
|---|---|---|
requestImagePixelBudget | 4,194,304 像素 | 单张请求图片的总像素预算 |
requestImageMaxBytes | 1 MiB | 单张请求图片在 Base64 编码前的字节目标 |
maxRequestImageBytes | 20 MiB | 保留图片的 Base64 载荷总量边界 |
maxRequestImages | 50 | 请求中保留图片的数量边界 |
数据来自 pi-ai 配置实现。这些是适配器参数,不是所有 GPT、Claude、Gemini 或 GLM 接口共有的服务限制。单图字节值也是处理目标,不能当作每张图片必然精确压到的大小。GitHub
Base64 会增加图片载荷。对长度为 n 的二进制内容,标准 Base64 字符数为 4 × ceil(n / 3)。例如,15 张各为 1 MiB 的已处理图片,仅 Base64 内容合计就会略高于 20 MiB,还没有计算正文、工具定义和 JSON 字段。
下面的脚本只计算本地文件的 Base64 体积,不发送请求:
from pathlib import Path
import sys
def base64_size(binary_bytes):
return 4 * ((binary_bytes + 2) // 3)
paths = [Path(name) for name in sys.argv[1:]]
if not paths:
raise SystemExit(
"Usage: python image_budget.py image1.png image2.jpg"
)
total = 0
for path in paths:
size = path.stat().st_size
encoded = base64_size(size)
total += encoded
print(f"{path.name}: binary={size}, base64={encoded} bytes")
print(f"Base64 payload only: {total / 1024**2:.3f} MiB")
print("Excludes prompts, history, tool definitions, and JSON overhead.")Harness 可能先缩放或重新编码图片,因此上传原图的大小不能直接代替最终请求体积。这个脚本适合解释体积变化;若用于精确验收,需要输入实际准备发送的图片版本。
遇到 IMAGE_OFFLOAD_REQUIRED,应检查图片保留及卸载流程,而不是直接提高所有限制。相关处理边界可查阅图片上下文转换实现。即使客户端允许更大的请求,网关或上游接口也可能先达到限制。
边界三:同一模型名称,可以对应不同的图片传输方式
模型可用,不代表任意协议都能承接同一种图片请求。
例如,Claude 的 Vision 文档与 Gemini 的图片理解文档分别说明了各自的图片内容结构与传递方式。原生接口、兼容接口以及文件上传接口,需要分别核对。
在 Harness 中,Provider 所选协议必须与目标通道一致。不要因为网关首页写着“支持 Gemini”,就把 Gemini 原生请求发到一个只接受 Chat Completions 的地址;也不要把某个接口返回的文件 ID 当成所有协议通用的图片地址。
直接 DeepSeek 适配器还有自己的图片处理路径。官方适配器说明记录了 Files API 引用及内联图片回退等机制。这与 pi-ai 的配置不是同一套参数,排查时应先确认实际使用哪个适配器。
通过 Treerouter 这样的 API 网关接入时,建议确认的是一个完整组合:具体模型 ID、具体协议、图片输入形式、当前通道限制。这四项一致,比反复测试“回复 hello”更接近真实业务。
如果企业要把这个组合用于客服截图、商品审核或内部报表,还应能够关联应用任务与模型请求。可以参考站内企业级 API 中转站调用日志验收,记录必要元数据,不要为了排错把密钥和业务图片内容复制进公共日志。
用两条请求路径缩小范围
准备一张不含敏感信息的测试图:上方放一个蓝色圆形,下方放一个黄色三角形。问题只问“上方和下方分别是什么形状、什么颜色”。不要把正确答案写在文件名里。
先在同一 API 通道上,用该协议的官方最小图片示例请求一次;再在 Harness 新会话里,用相同模型、相同图片和相同问题请求一次。
两次都失败,优先核对图像能力、账号权限和通道支持。独立请求成功而 Harness 失败,重点检查适配器、图片声明和实际请求转换。新会话成功而旧会话失败,则检查旧附件、累积载荷和历史上下文。
这不是模型能力测评,只是连接验收。一次答对也不能证明它适合识别复杂票据、密集截图或工业缺陷。连接通过之后,再用真实业务样本评估准确率,并记录无法判断的情况。
需要进一步定位某一轮请求时,可参考Harness 轨迹视图排查文章。旧文界面以其标注版本为准,重点寻找本次实际调用,而不是只看会话顶部的模型名称。
把“支持图片”写成可复用的接入记录
上线前,可以为每个图像任务保存一张简短记录:
- 任务类型:截图理解、图表问答,或商品属性提取。
- 模型及通道:实际模型 ID、Provider、适配器和协议。
- 输入条件:图片数量、格式、尺寸及实际请求体积。
- 验收结果:独立 API 是否通过,Harness 新会话是否通过。
- 失败处理:何时要求用户重传图片,何时切换已验证的路线。
如果业务需要换模型,重新验证这张记录,而不是只替换一个名字。纯文本推理模型可以承接图片分析后的文字加工,但它不能因此被视为已经接收了原始图像。
准备接入时,先查看当前模型目录,核对目标视觉路线,再注册并完成一个单图测试。让第一条成功调用同时包含正确图片输入和可检查的结果,后续扩展多图、多轮和多模型时才有明确的参照。






