DeepSeek Harness Vision Model Configuration

DeepSeek Harness 视觉模型配置：图片不支持错误排查

作者
DeepSeekAgent.io 编辑部
发布
更新

在 DeepSeek Harness 中接入 OpenAI 兼容的视觉模型时，即使上游模型确实能处理图片，也可能遇到“当前模型不支持图片”的提示。原因通常不在图片本身，而在 DSH 的模型能力声明：模型条目只有明确包含 image 输入模态，Session 才会接收图片附件。

本文根据官方 @deepseek-ai/dsh-llm-deepseek 包文档、源码和社区问题记录，说明如何配置、验证与排错。文中涉及 Web 模型编辑器的限制以 v0.1.2-alpha.4 的公开讨论和源码为界；后续版本可能改变界面行为。

先理解错误出现在哪一层

一张图片进入模型之前，会经过至少三层判断：

  1. 上游模型或兼容网关是否真的接受图像输入。
  2. DSH 模型目录是否把该模型声明为 text 与 image。
  3. 图片大小、像素预算和传输方式是否满足 Provider 限制。

DSH 的 Session Controller 会先读取当前模型的 inputModalities。如果其中没有 image，附件会在请求模型之前被拒绝，并返回 MODEL_DOES_NOT_SUPPORT_IMAGES。因此，上游接口支持图片并不等于 DSH 已经知道它支持图片。

为什么自定义模型容易被识别为纯文本

官方 llm-deepseek 插件的模型配置允许 inputModalities，目前有效值是 text 和 image，默认值只有 text。如果只填写模型 ID、名称、上下文窗口与最大输出长度，自定义条目会自然落到纯文本默认值。

在 alpha.4 的 Web 模型编辑器中，界面只保存 id、name、contextWindow 和 maxTokens，没有提供图片输入能力的开关。这也是“接口明明能看图，DSH 却拒绝附件”的常见来源。

在 Composition 中声明视觉能力

如果兼容接口已经确认支持图片，可以在 @deepseek-ai/dsh-llm-deepseek 的 Composition 配置中为模型加入 inputModalities：

- name: '@deepseek-ai/dsh-llm-deepseek'
  config:
    apiKeyEnv: YOUR_API_KEY
    baseURL: https://your-openai-compatible-endpoint.example/v1
    models:
      - id: your-vision-model
        name: Your Vision Model
        inputModalities:
          - text
          - image
        contextWindow: 128000
        maxTokens: 8192
        imagePixelBudget: 4194304
        imageMaxBytes: 10485760

这里的数值只是结构示例，应按真实 Provider 文档设置。imagePixelBudget 必须是正整数，也可以使用插件支持的 low；imageMaxBytes 用来限制单张图像大小。

一个容易忽略的规则是：显式提供 models 列表会整体替换插件的默认模型列表，而不是在默认列表后追加一项。需要继续使用的模型都应复制进新列表。Settings 中的模型列表同样可能整体覆盖 Composition 的列表，所以修改前应先导出或备份当前配置。

官方 DeepSeek 路由的默认行为

官方包文档说明，直接使用 deepseek-official 路由且省略 models 时，会提供一组默认目录，其中包括实验性的视觉模型条目。这与自定义 OpenAI 兼容模型不是同一条路径。

如果填写了一个未列入目录的模型 ID，插件可以把它透传给接口，但会把它当作纯文本模型。透传成功只证明文本请求能到达上游，不会自动探测视觉能力。

按顺序排查图片失败

1. 先验证上游接口

用 Provider 官方示例直接发送一张小图，确认相同的模型 ID、Endpoint 和 API Key 能完成图像请求。不要只依据模型名称中含有 vision 或厂商宣传判断。

2. 检查当前选中的模型

确认 Session 实际使用的模型就是刚配置的视觉条目，而不是名称相近的文本模型。切换模型后新建一次测试 Session，可以减少旧 Session 状态干扰。

3. 检查 inputModalities

模型条目必须同时包含 text 与 image。如果只通过 Web 编辑器保存过模型，要留意编辑器是否把未显示字段覆盖掉。

4. 缩小测试图片

先使用普通 JPEG 或 PNG、小尺寸、低于 Provider 限额的图片。模型能力声明正确后仍失败，再检查 imagePixelBudget、imageMaxBytes、MIME 类型和上游限制。

5. 区分入口与输出能力

DSH 当前的图片支持重点是输入附件。官方包文档明确说明，外部图片 URL 直传和 Assistant 图片输出并不受支持。把图片先作为持久附件交给 Session，与要求模型返回一张图片，是两种不同能力。

安全与兼容性提醒

  • 只为真正支持图像的模型声明 image，错误声明会把失败推迟到上游，并产生更难理解的报错。
  • 自建网关可能记录或转发图片，发送截图前检查其中的密钥、个人信息和客户数据。
  • alpha 版本的配置界面和字段可能变化；升级后应重新做一轮小图测试。
  • 不要把社区讨论中的临时配置方法当作稳定 UI 功能，最终以正在使用版本的 Schema 与官方文档为准。

相关阅读

常见问题

为什么模型官网支持图片，DSH 仍说不支持？

DSH 不会只根据模型名称自动推断能力。自定义条目默认是纯文本，需要在模型目录中明确声明 inputModalities: [text, image]。

只在 Web 界面里配置可以吗？

alpha.4 的公开问题记录显示，当时的模型编辑器没有暴露 inputModalities。如果当前版本仍没有该字段，应使用受版本支持的 Composition 配置方式，并在 UI 保存后检查它是否被保留。

加上 image 后就一定能看图吗？

不一定。它只通过 DSH 的本地能力检查；上游模型、兼容网关、图片格式与大小仍必须真正支持图像请求。