企业官网建设流程全解析

DeepSeek Harness 本身是一个调度层，不是模型；ModLens 是给它补视觉能力的插件；GLM-5.3 Flash 是真正做图理解的视觉模型。三者接好之后，你的 Harness Agent 才能回答“这张图里有什么”这类问题。

这篇内容适合已经在本地跑过 Harness、想把识图能力加进来的开发者，也适合刚看到配置目录不知道从哪下手的入门者。我会按安装、插件接入、Skill 配置、批量测试、问题排查的顺序拆开写，重点回答一个关键问题：怎么知道识图能力是真的生效，而不是只是把图片路径传进去。

很多人在这个环节卡住，不是模型不会用，而是没搞清“Harness、插件、视觉模型”三者之间的分工。下面先把这个关系理顺。

1. 先搞清楚：Harness、ModLens、GLM-5.3 Flash 分别负责什么

1.1 DeepSeek Harness 不是模型，是调度层

很多入门者以为装好 DeepSeek Harness 就等于有一个能聊天的模型。实际上，Harness 更像一个外壳，负责管理对话、任务、工具调用、插件和 Skill。它本身不直接产生视觉理解，而是把用户请求拆给正确的后端模型和插件。

举个例子，用户发了一张合同截图，问“这里面的金额是多少”。Harness 要做的不是自己去读图，而是先判断这个问题需要视觉能力，再调用已经配置好的识图插件，最后把结果放回对话里。这个“判断、调度、组装、回复”的过程，就是 Harness 的核心作用。

所以当你给 DeepSeek Harness 配置识图能力时，重点不是让 Harness 学会看图，而是让它在正确的时候找到正确的识图链路。这也是为什么后面要单独配置 Skill，而不是装一个插件就结束。

1.2 ModLens 插件解决的是图片接入问题

ModLens 这个名字容易让人误以为它本身就是视觉模型。它其实是插件层，核心工作是接收图片、检查格式、做预处理，然后调用视觉模型，再把结果转换成对话文本返回给 Harness。

为什么要单独拆一层？因为 Harness 的对话模块通常只处理文本。用户上传一张图，Harness 不能直接把二进制文件扔给对话模型。需要经过 ModLens 把图片转成模型能识别的请求格式。

插件层还有一个实际好处：你可以换不同的视觉模型，而不需要改动 Harness 主程序。今天用 GLM-5.3 Flash，明天换成其他模型，改的只是插件配置里的模型标识和密钥，不用重新做一套流程。

1.3 GLM-5.3 Flash 承担具体视觉推理

GLM-5.3 Flash 在这里是视觉理解后端。它接收 ModLens 处理好的图片和问题，输出图片描述、物体识别、文字提取等结果。这个模型是否支持本地部署、支持哪些图片格式、最大输入尺寸是多少，需要以模型服务的文档为准。

我一般会先确认一次：当前 Harness 接的是 API 型模型，还是本地模型。因为这两种方式的配置、资源和错误表现差别很大。

如果是 API 型模型，本地不需要 GPU，只要网络通、密钥对，就能调用。如果要在本地跑视觉模型，就要关心模型体积、显存、量化方式，以及本地调用速度是否满足交互需求。标题里提到的 GLM-5.3 Flash，我会先按“走接口调用”来理解。实际落地时，你要先看服务商给的模型标识和调用方式，再决定配置字段。

1.4 三层架构下的请求链路

当用户发来一张图片并提问“图里有什么”，实际链路是：

1. Harness 收到消息，发现需要视觉能力。
2. 调起 ModLens 插件，读取图片。
3. ModLens 对图片做格式检查、压缩和编码。
4. 调用 GLM-5.3 Flash，带上图片信息和用户问题。
5. 模型返回文本，ModLens 把结果交回 Harness。
6. Harness 把最终结果回复给用户。

这套链路跑通后，你看到的是一次自然的对话回复。而真正发生的是六步协作。后续排查时，也要按这个链路逐段检查。

注意：这里不要急着调参数。先把“调度层、插件层、模型层”的关系确认清楚，后面配置时你才知道日志里该看谁的记录。

2. 环境准备：安装、注册和密钥是第一个卡点

2.1 安装 DeepSeek Harness 的常见路径

先说我经常遇到的第一个问题：安装过程卡在依赖处理上。社区里经常说的“deepseek harness 卡在 pnpm dsh web”基本就是这种问题。DeepSeek Harness 这类项目大多依赖 Node.js 生态，安装时要用 pnpm 管理依赖，再通过 dsh 命令启动 Web 管理界面。

建议按这个顺序确认环境：

node -v npm -v pnpm -v

如果 pnpm 不存在，先安装 pnpm。不要跳过这一步，因为直接用 npm 装依赖在某些项目里会因为 lockfile 版本不一致而失败。

然后进入项目目录：

pnpm install pnpm dsh web

启动后看日志输出的本地地址，再打开浏览器访问。如果启动卡住，优先看日志是停在下载依赖、编译还是端口监听。不要反复重启，先看日志输出到底卡在哪一步。

有些情况下，pnpm install本身就很慢，这通常和网络环境、镜像源有关。如果下载依赖一直超时，可以先确认能否正常访问公共代码仓库和 npm 镜像。这里不是 Harness 本身的问题，而是包管理器的网络链路问题。

2.2 准备 GLM-5.3 Flash 的访问密钥

识图模型如果是通过接口调用，就需要访问密钥。配置前先在模型服务商的控制台创建 API Key。密钥不要写进博客或项目仓库，建议用环境变量加载。

export MODLENS_VISION_API_KEY="你的密钥"

再启动 Harness，让进程读取这个环境变量。至于变量名叫什么，不同版本可能不同。我在本地测试时会先看项目里的.env.example或配置样例，找到视觉模型对应的字段，再决定设置哪个变量。

这里最容易踩的坑是：密钥配置写好了，但 Harness 进程是在设置环境变量之前启动的，结果进程里根本没有这个变量。重启进程就好了。

另外，如果你用 Windows 环境，环境变量语法和 Linux/macOS 不一样。Windows 的 PowerShell 下可以用：

$env:MODLENS_VISION_API_KEY="你的密钥"

设置完成后再启动进程。不要用 Linux 的export语法直接复制，否则会报错。

2.3 确认前端和 Web 管理界面能正常打开

安装完先不要急着配识图。确认主页能打开，模型能发起普通对话，再进入下一节。如果普通对话都报错，说明是模型接入问题，不是识图插件问题。

判断标准很简单：

• 页面能打开：Harness 启动正常。
• 普通文本对话有回应：基础模型连接正常。
• 能看到插件或技能管理入口：说明插件系统已加载。

这三点都满足之后，再开始装 ModLens。跳过这一步直接配识图，容易把“模型调用失败”和“识图插件失败”混在一起，排查成本会高一倍。

3. 给 Harness 安装 ModLens 插件并接入视觉模型

3.1 安装 ModLens 插件

每个 Harness 的插件安装命令不一定一样。如果你的版本支持插件命令，通常会是这样：

dsh plugin add modlens dsh plugin list

如果不支持命令，就在配置目录的插件列表里加入modlens声明，然后重新启动。判断插件是否成功的标准是：插件管理页面里能看到 modlens，并且状态不是“未启用”或“缺失依赖”。

安装完插件后，最好先看一次插件的默认配置。有些插件自带示例，有些需要你手动补模型字段。不要以为plugin add完成就万事大吉，这相当于装好了硬件驱动，但应用软件还没装全。

3.2 在配置里指定视觉模型

安装好插件后，还需要告诉插件使用哪个视觉模型。这个配置通常写在独立的 config 文件或 harness 配置里。下面是一个示意结构，实际字段以你的版本为准：

vision: provider: modlens model: glm-5.3-flash api_key_env: MODLENS_VISION_API_KEY max_image_size: 1280 timeout: 30

几个参数的判断标准：

• provider 固定写 modlens，表示视觉能力通过该插件处理。
• model 写 GLM-5.3 Flash 在服务商侧的模型标识。
• api_key_env 写环境变量名，不是直接写密钥本身。
• max_image_size 控制图片最长边。设小一点，传输更快，但识别小字或细节可能变差。
• timeout 控制单张图的等待时间。超时太短，大图会频繁失败；太长，批量任务会卡住。

我建议先按默认值跑一次。如果单张图片识别慢，再把 timeout 调大。如果图片体积太大，先压缩，不要一味增加超时时间。压缩能同时降低传输耗时和接口压力，比单纯改超时更有效。

注意：max_image_size 不代表模型真实输入尺寸，只是插件在发送前的缩放上限。模型是否支持更大图，要看模型接口限制。

3.3 验证“模型是否真的被 Harness 调用”

配置完成后，很多人只在界面上传了一张图，看到有文字输出就说“能用了”。但更可靠的做法是看调用日志。先发一张简单的图片，问“这张图里有什么”，然后去日志里确认：

• 是否有图片预处理记录；
• 是否出现模型名称 glm-5.3-flash；
• 返回内容是否是模型生成的文本，而不是固定模板。

如果返回内容一直是一句“我无法查看图片”，那说明 ModLens 可能没被调到，或者请求没有真正发到视觉模型。这时候不要改 prompt，先排查配置。

还可以做一个快速验证：把密钥故意写错，再发一次识图请求。如果日志里立刻出现鉴权错误，说明链路已经走到了视觉模型；如果没有任何变化，说明插件可能根本没调用模型。

这是一个很实用的判断手段。它比看 UI 上的成功提示更可靠，因为 UI 可能只是把图片加进对话，并没有真正交给模型处理。

3.4 常见配置错误

我整理过几个最常见的配置错误，供你对照：

这条清单不需要背，出问题时按顺序过一遍就行。

4. 配置识图 Skill：让 Agent 在对话里主动调用视觉能力

4.1 什么是 Skill，为什么需要单独配

插件装好不等于 Agent 会自动识图。很多 Harness 类项目里，技能需要单独声明。系统才知道“遇到图片时应该调用哪个插件”。

ModLens 插件是执行能力，Skill 是触发规则。只装插件不配 Skill，你可能会遇到“能识图但是每次都要手动指定工具”的情况。配置 Skill 的作用，是把“用户上传图片并提问”这个场景和“调用 ModLens 视觉链路”这个动作绑定起来。

你可以把 Skill 理解为给 Agent 的一条工作流程说明：什么时候打开视觉能力、图片从哪里读取、结果返回到哪里、输出格式是什么。没有这条说明，Agent 即使手里有工具也不知道什么时候该用。

4.2 最小 Skill 配置示例

假设项目使用skills/image_description/目录，里面放两个文件：一个描述文件，一个配置。下面是典型结构：

name: describe_image description: 当用户上传图片并询问图片内容时，使用 ModLens 与 GLM-5.3 Flash 生成描述 vision_model: glm-5.3-flash input: image: file_path output: format: text

这个 Skill 的触发条件比较简单：用户上传图片，并且提问内容包含“描述”“里面有什么”“识别”“看图”等意图。具体触发条件取决于 Harness 的实现，有些项目会要求你在配置里写关键词或意图模板。

我的经验是，描述文本不要写得太抽象。比如“处理图片”就不够具体，因为模型不知道图片是用来做 OCR、物体识别还是场景理解。写成“当用户上传图片并询问图片内容时”会更清楚。

4.3 测试单张图片识图

配置完 Skill 后，先跑单张图，不要批量。测试目标有三个：

1. 上传图片后，Harness 是否自动识别出“需要调用视觉能力”。
2. ModLens 是否正确拿到图片路径，而不是把路径当文本。
3. 返回结果是否包含图片内容，而不是报错或空回复。

我一般会在本地准备三张不同类型的图片：

• 一张纯文字截图，测试 OCR 能力；
• 一张带物体的生活照片，测试物体识别；
• 一张复杂图表，测试边界能力。

如果纯文字能识别，说明链路基本通；如果复杂图表失败，可能是模型能力或尺寸限制，先不要急着调插件。

记录结果时可以这样整理：

跑完单张图，记录一下耗时。如果一张图超过几十秒，批量处理时就要特别注意超时和队列设计。

5. 批量识图：文件路径、图片格式和失败重试

5.1 批量任务不能直接复制单张流程

单张图片测试通过后，很多人会写一个循环遍历整个目录。听起来没问题，但批量识图真正麻烦的不是识别，而是输入路径、输出命名、失败重试。

本地文件批量识图时，插件需要读取文件的绝对路径。如果路径里有中文、空格或符号，可能在传给模型前就出错。建议先在脚本里做一次文件过滤：

const fs = require("fs"); const path = require("path"); const dir = "/path/to/images"; const files = fs.readdirSync(dir) .filter(f => [".jpg", ".jpeg", ".png", ".webp"].includes(path.extname(f).toLowerCase())); for (const file of files) { const abs = path.join(dir, file); try { const result = await describeImage(abs); fs.writeFileSync(abs + ".txt", result); } catch (err) { console.error("failed:", file, err.message); } }

我用的是 JavaScript 示意，如果你的 Harness 支持脚本扩展，思路是一样的。重点是批量执行时必须有 try/catch，不能让一张失败导致整个任务退出。

5.2 图片格式和大小限制

常见模型支持的格式一般是 jpg、png、webp。有些不支持 HEIC，或者支持但识别效果不稳定。批量跑之前先确认目录里没有特殊格式。

图片尺寸方面，建议先看接口限制。如果单张图超过限制，先压缩再发送。插件一般会做预处理，但如果你手动写脚本调用接口，就要自己处理。

判断标准：

• 单张识别成功，记录耗时；
• 连续跑 10 张，看成功率；
• 记录失败的是不是集中在某些大图或特殊格式上。

如果失败集中在同一个格式，先格式转换。如果失败集中在特定大小，先压缩。不要把所有失败都归结成“模型能力不行”。

5.3 输出文件命名和断点续跑

批量任务里，输出命名很容易乱。不要用图片原文件名加固定后缀，因为如果你跑两轮，会覆盖上一轮结果。建议这样设计：

• 输出目录单独放，不要和原图混在一起；
• 文件名带时间戳或任务批次；
• 失败列表单独记录，方便第二轮重跑。

示例：

output/ 20250312_batch_001.jpg.txt 20250312_batch_002.jpg.txt failed_20250312_batch.log

这样即使中途中断，也能通过 failed 日志知道哪些图片没有处理，实现简单的断点续跑。

5.4 超时、限流和重试策略

批量识图时最容易被忽略的是限流。视觉模型接口通常有每分钟调用次数限制。不要一上来就把并发开满。先串行跑，再逐步提高并发。

我建议的批量节奏是：

1. 第一批只跑 5 张，观察成功率和耗时。
2. 如果全部成功，再跑 50 张。
3. 如果出现限流错误，降低并发或增加重试间隔。

重试要有上限，一般 2 到 3 次即可，超过就写入失败日志。不要让任务无限重试，否则批量任务可能一直卡在同一个文件上。

注意：任务卡住时不一定是模型挂了，先看是不是某张图片导致进程阻塞，再看输出目录有没有权限问题。

6. 常见问题排查顺序与实用边界

6.1 常见问题排查表

针对识图场景，我常用的排查顺序是先看现象，再看输入，再看配置，最后看模型接口。不要一开始就改模型。

这张表不是万能清单，但覆盖了 80% 的识图配置问题。你可以复制成自己的排错手册，以后遇到类似问题先按表格对一遍。

6.2 低配置环境能跑到什么程度

如果识别走的是 API，本地不需要很强 GPU，主要看内存和 CPU。Harness 进程本身、图片解码、预处理都会占资源。低配机器跑单张没问题，跑批量时页面可能卡顿。

我建议先观察三点：

• 单张识别时 CPU 是否飙升；
• 批量处理时内存有没有持续增长；
• 批量任务跑完后内存是否回落正常。

如果内存一直涨，大概率是任务队列或图片缓存没释放。这时候不要继续加并发，先定位内存回收逻辑。

如果希望在本地跑视觉模型，那就要看模型体积和显存。我建议先看模型文件大小和量化方式，再用小图测一次显存峰值。比如模型量化到 4bit，显存占用会比 16bit 低很多，但识别精度也可能下降。

6.3 不要对视觉模型抱有过高预期

视觉识别不是 OCR 万能工具。复杂图表、长文本截图、模糊照片、密集小字，都可能出错。识图能力解决的是“把图片内容变成可对话的文本”，不等于每个像素都能精准还原。

处理策略是：重要图片先小图验证，再决定要不要全量处理。如果主要需求是提取文字，可以再加一层 OCR 工具；如果需求是理解场景，视觉模型更合适。

还有一点，不同模型对中文文字识别的能力差异比较大。如果你是拿中文截图测试，失败后不要急着否定整个链路，先换一张清晰的大字号文字图再试一次。

6.4 成本与替代方案的取舍

按接口调用识图，通常按请求次数或 Token 计费。批量任务先估算数量，再决定是分批处理还是换本地模型。不是所有场景都要上多模态大模型。

更务实的做法是：把识图能力拆成两个入口。一是日常对话里的临时识图，走 GLM-5.3 Flash；二是固定流程的批量 OCR，走更轻量的专用工具。这样既保证能力完整，也不会因为批量任务烧掉太多成本。

如果你只是想把 Harness 调通，默认配置已经够用。如果要做长期生产任务，还要看接口的配额、并发上限、失败计数和日志轮转。这些不是插件的功能问题，而是工程化问题。

这篇文章里没有官方文档级别的固定答案，因为 DeepSeek Harness 的插件机制、ModLens 的版本、GLM-5.3 Flash 的接口约束，都可能在落地时和本文示例不同。我的建议是：先跑通最小链路，再逐步加复杂度。很多问题不是工具能力不够，而是环境、密钥、路径和参数没有对齐。先把单任务跑稳，再谈批量和接口，识图能力才能真正用起来。