DeepSeek Harness: 多模态支持
最后更新:2026-08-31
文字只是 Agent 理解世界的一种方式——图片、音频、视频才是真实世界的语言。DSH 的多模态支持让 Agent 不只"读代码",还能"看界面""听反馈""观视频",极大扩展了 Agent 的感知边界。
💡 提示:多模态是 DSH 的 developer preview 特性,功能持续迭代中。当前最稳定的是图像输入,音频和视频支持仍在完善。
📋 前置知识:已完成 06-tools.md,了解工具系统基础
1. 你将学到
- DSH 多模态架构概览
- 图像输入处理方式
- 音频/视频输入支持状态
- 多模态工具集成
- 文件附件与解析机制
2. 多模态架构概览
(1) 多模态数据流
graph TB
subgraph 输入源
IMG[图像<br/>PNG/JPG/WebP]
AUD[音频<br/>MP3/WAV]
VID[视频<br/>MP4/WebM]
DOC[文档<br/>PDF/CSV]
end
subgraph DSH处理
PARSE[附件解析器]
ENCODE[多模态编码]
LLM[LLM 多模态推理]
end
subgraph 输出
TEXT[文本回复]
TOOL[工具调用]
end
IMG --> PARSE
AUD --> PARSE
VID --> PARSE
DOC --> PARSE
PARSE --> ENCODE
ENCODE --> LLM
LLM --> TEXT
LLM --> TOOL
(2) 多模态支持矩阵
| 输入类型 | 格式支持 | 稳定性 | 最大尺寸 | 说明 |
|---|---|---|---|---|
| 图像 | PNG, JPG, WebP, GIF | ✅ 稳定 | 20MB/张 | 最成熟的多模态能力 |
| 音频 | MP3, WAV, OGG | ⚠️ 实验性 | 50MB | 需要支持音频的模型 |
| 视频 | MP4, WebM | ⚠️ 实验性 | 100MB | 逐帧提取分析 |
| 文档 | PDF, CSV, XLSX | ✅ 稳定 | 50MB | 文本提取 + 结构化 |
(3) 模型要求
多模态功能依赖 LLM 的多模态能力:
| 模型 | 图像 | 音频 | 视频 | 文档 |
|---|---|---|---|---|
| deepseek-chat | ✅ | ❌ | ❌ | ✅ |
| gpt-4o | ✅ | ✅ | ✅ | ✅ |
| gpt-4-vision | ✅ | ❌ | ❌ | ✅ |
| claude-3.5-sonnet | ✅ | ❌ | ❌ | ✅ |
3. 图像输入处理
(1) Web UI 添加图像
在 Web UI 对话区中,支持拖拽或粘贴添加图像:
TEXT
📖 仅展示
┌─ Chat Area ──────────────────────────────┐
│ │
│ 👤 Alice: │
│ 📎 [screenshot.png] [ui-mockup.jpg] │
│ 这两个 UI 设计哪个更好? │
│ │
│ [Send] │
└───────────────────────────────────────────┘
支持的操作:
- 拖拽图片到对话区
- 粘贴剪贴板中的图片(Ctrl+V)
- 点击附件按钮选择文件
- 单次最多 5 张图片
(2) CLI 模式添加图像
▶ 示例 1CLI 模式附加图像
BASH
# 启动 CLI 并附加图像
dsh cli --attach ./screenshot.png
# 在对话中使用 /attach 命令
> /attach ./ui-mockup.jpg
> 这个 UI 有什么问题?
# 附加多张图像
> /attach ./before.png ./after.png
> 这两次修改有什么区别?
输出:
TEXT 📖 仅展示📎 Attached: ./screenshot.png (1.2MB) 🤖 DSH CLI ready. Type your message...
(3) SDK 模式附加图像
▶ 示例 2Python SDK 发送图像
PYTHON
from dsh import DSHClient
client = DSHClient(base_url="http://127.0.0.1:3080")
session = client.create_session(workspace="/home/alice/project")
# 附加单张图像
response = session.send(
"这个 UI 截图中有什么问题?",
images=["./screenshot.png"]
)
print(response.content)
# 附加多张图像进行对比
response = session.send(
"对比这两个设计,哪个更好?",
images=["./design-a.png", "./design-b.png"]
)
交互流程:
🤖 Agent: 正在分析截图... 🔍 Image analysis: 检测到 UI 界面 🤖 Agent: 这个 UI 截图显示了一个登录页面...⚠️ 你的实际分析内容取决于图片内容和模型,但分析流程应相似。
(4) 图像分析实战
▶ 示例 3UI Bug 分析
TEXT
📖 仅展示
👤 Alice: [附加 error-page-screenshot.png]
这个错误页面有什么问题?帮我修复
🤖 Agent:
🔍 Analyzing image...
我看到了以下问题:
1. 错误信息文本溢出容器边界
2. "重试"按钮被截断,只显示一半
3. 背景色与设计规范不一致(应为 #f5f5f5 而非白色)
📝 Using tool: file_edit (edit)
→ Path: src/pages/ErrorPage.tsx
→ Fix 1: 添加 text-overflow: ellipsis
→ Fix 2: 调整按钮 margin
→ Fix 3: 修改背景色
⚠️ Approval Required: Edit file src/pages/ErrorPage.tsx
(5) 图像处理限制
| 限制项 | 说明 |
|---|---|
| 单张最大 | 20MB |
| 单次最多 | 5 张 |
| 分辨率 | 建议不超过 4096×4096 |
| 动画 GIF | 仅取第一帧 |
| 格式转换 | 自动转为模型支持的格式 |
4. 音频/视频输入
(1) 音频输入(实验性)
音频输入需要模型支持音频理解(如 GPT-4o):
▶ 示例 4SDK 发送音频
PYTHON
# 发送音频文件
response = session.send(
"转录这段音频并总结要点",
audio=["./meeting-recording.mp3"]
)
print(response.content)
# 音频转录结果和总结...
交互流程:
🤖 Agent: 正在转录音频... 🔊 Audio transcription: 今天我们讨论了项目进度... 🤖 Agent: 音频转录完成,要点总结如下...⚠️ 音频功能为实验性,实际输出取决于模型和音频质量。
(2) 视频输入(实验性)
视频处理采用逐帧提取策略:
graph LR
VID[视频文件] --> EXTRACT[帧提取<br/>每秒1帧] --> SELECT[关键帧选择<br/>场景变化检测] --> ENCODE[多帧编码] --> LLM[LLM 分析]
▶ 示例 5SDK 发送视频
PYTHON
# 发送视频文件
response = session.send(
"分析这个演示视频,列出展示的功能点",
video=["./demo.mp4"]
)
print(response.content)
# 1. 用户登录功能 (0:00-0:15)
# 2. 仪表盘展示 (0:15-0:45)
# ...
交互流程:
🤖 Agent: 正在分析视频... 🎬 Frame extraction: 120 frames → 15 key frames 🤖 Agent: 视频分析完成,展示的功能点如下...⚠️ 视频功能为实验性,帧提取和内容分析取决于模型。
(3) 当前限制
音频和视频功能仍处于实验阶段:
| 限制 | 音频 | 视频 |
|---|---|---|
| 最大时长 | 10 分钟 | 5 分钟 |
| 最大文件 | 50MB | 100MB |
| 模型要求 | GPT-4o 等 | GPT-4o 等 |
| 帧提取 | — | 每秒 1 帧,最多 300 帧 |
| 稳定性 | ⚠️ 可能超时 | ⚠️ 可能超时 |
5. 文档附件与解析
(1) 支持的文档格式
| 格式 | 解析方式 | 输出 |
|---|---|---|
| 文本提取 + OCR | 结构化文本 | |
| CSV | 解析行列 | 表格数据 |
| XLSX | 解析工作表 | 表格数据 |
| DOCX | 文本提取 | 结构化文本 |
| Markdown | 直接读取 | 原始文本 |
▶ 示例 6附加 PDF 文件
PYTHON
# 分析 PDF 文档
response = session.send(
"总结这份技术文档的核心要点",
files=["./api-specification.pdf"]
)
print(response.content)
交互流程:
🤖 Agent: 正在解析 PDF 文档... 📄 Document parsed: 24 pages, 8,500 characters 🤖 Agent: 这份技术文档的核心要点如下...⚠️ 你的实际分析内容取决于文档内容和模型。
(2) CSV 数据分析
▶ 示例 7分析 CSV 数据
PYTHON
# 分析 CSV 数据
response = session.send(
"分析这份销售数据,找出趋势和异常值",
files=["./sales-2026.csv"]
)
print(response.content)
# 数据分析结果...
Agent 也可以用工具进一步处理:
TEXT
📖 仅展示
🤖 Agent:
📊 Analyzing CSV data...
→ Rows: 12,450
→ Columns: 8
→ Date range: 2026-01 to 2026-08
Key findings:
1. 月均增长 12%,但 3 月下降 8%(疑似季节性)
2. Top 3 产品占总收入 65%
3. 客户留存率从 72% 降至 68%
🔧 Using tool: shell
→ Command: python3 -c "import pandas; ..."
→ Generating visualization...
6. 多模态工具集成
(1) 多模态与工具协同
Agent 可以将多模态输入与工具调用结合:
graph TB
INPUT[多模态输入] --> AGENT[Agent 分析]
AGENT -->|图像 → 代码| FE[file_edit]
AGENT -->|视频 → 脚本| SH[shell]
AGENT -->|文档 → 数据库| DB[database.query]
▶ 示例 8图像 + 工具协同
TEXT
📖 仅展示
👤 Bob: [附加 api-response-screenshot.png]
这个 API 响应格式不对,帮我查看代码
🤖 Agent:
🔍 Analyzing screenshot...
→ Expected format: { data: [...], meta: {...} }
→ Actual format: { results: [...] }
🔍 Using tool: search
→ Pattern: "results"
→ Type: content
→ Found in: src/api/handlers.ts:45
📝 Using tool: file_edit (read)
→ Reading src/api/handlers.ts
📝 Using tool: file_edit (edit)
→ Fixing response format at line 45-52
→ Changing "results" to "data", adding "meta" field
(2) 批量图像处理
▶ 示例 9批量图像 + 文件编辑
PYTHON
import glob
screenshots = glob.glob("./screenshots/*.png")
response = session.send(
"查看所有截图,找出有 UI 问题的页面,逐一修复",
images=screenshots[:5] # 最多 5 张
)
交互流程:
🤖 Agent: 正在分析 5 张截图... 🔍 Image 1: 登录页 → 检测到按钮错位 🔍 Image 2: 仪表盘 → 无明显问题 🔍 Image 3: 设置页 → 文本溢出 🔧 Using tool: file_edit (edit) → 修复问题页面 ✅ 已修复 2 个页面的 UI 问题⚠️ 批量分析的结果完全取决于截图内容和模型判断。
(3) 多模态链式推理
TEXT
📖 仅展示
👤 Alice: [附加 architecture-diagram.png]
根据这个架构图生成对应的 Docker Compose 配置
🤖 Agent:
🔍 Analyzing architecture diagram...
→ 识别到 4 个服务:API, Worker, Database, Cache
→ 连接关系:API → Database, API → Cache, Worker → Database
📝 Using tool: file_edit (create)
→ Creating docker-compose.yml
→ 4 services with proper networking
✅ Docker Compose 配置已生成,包含:
- api-service (Express.js, port 3000)
- worker-service (Node.js, background jobs)
- postgres (PostgreSQL 16, volume mounted)
- redis (Redis 7, cache layer)
7. 配置与优化
(1) 多模态配置
YAML
# dsh.config.yaml
multimodal:
# 图像设置
images:
max_size_mb: 20
max_per_message: 5
resize_large: true # 自动缩放过大图片
max_resolution: [4096, 4096]
# 音频设置
audio:
max_duration_minutes: 10
max_size_mb: 50
transcription_model: "whisper-1"
# 视频设置
video:
max_duration_minutes: 5
max_size_mb: 100
frame_rate: 1 # 每秒提取帧数
max_frames: 300
# 文档设置
documents:
max_size_mb: 50
pdf_ocr_enabled: true
csv_max_rows: 100000
(2) 性能优化
多模态输入会增加 token 消耗和响应时间:
| 优化策略 | 说明 | 效果 |
|---|---|---|
| 图片压缩 | 上传前压缩到合适分辨率 | 减少 50-80% 图像 token |
| 关键帧选择 | 视频只发送关键帧 | 减少 90% 视频帧 |
| 文本提取 | PDF 优先提取文本而非 OCR | 更快更准 |
| 分批发送 | 大量图片分批发送 | 避免超时 |
❓ 常见问题
Q 所有模型都支持图像输入吗?
A 不是。需要使用支持视觉的模型,如 DeepSeek-VL、GPT-4o、Claude 3.5 Sonnet 等。普通文本模型无法处理图像。
Q 图像质量会影响 Agent 理解吗?
A 会。低分辨率、模糊、光照不足的图片可能导致 Agent 误判。建议上传清晰、高分辨率的图像。
Q 音频功能什么时候稳定?
A 音频和视频功能仍在 developer preview 阶段,官方未公布稳定时间表。建议仅用于非关键场景。
Q 多模态消耗多少额外 token?
A 图像约 85-170 tokens/张(取决于分辨率),音频约 150 tokens/分钟,视频约 85 tokens/帧。具体取决于模型和编码方式。
Q 可以让 Agent 自己截图吗?
A 可以。通过 Playwright 等工具插件,Agent 可以打开浏览器、截图、然后分析截图。这需要安装社区插件。
Q PDF 的 OCR 准确吗?
A 对于文字清晰的 PDF,直接文本提取(非 OCR)准确率接近 100%。扫描件和手写内容依赖 OCR,准确率较低。 ---
📖 小节
- DSH 多模态支持图像(稳定)、音频/视频(实验性)、文档(稳定)
- 图像输入:Web UI 拖拽/粘贴,CLI
/attach,SDKimages参数 - 音频/视频需要支持多模态的 LLM 模型
- 文档解析支持 PDF、CSV、XLSX 等格式
- 多模态与工具协同:图像→代码修复、文档→数据分析
- 配置文件可调整尺寸限制、帧率、OCR 开关等
- 多模态增加 token 消耗,需注意优化策略
📝 作业
1. ⭐ 基础题:在 Web UI 中上传一张 UI 截图,让 Agent 描述截图中的内容。记录 Agent 的分析结果和使用的工具。
2. ⭐⭐ 进阶题:上传一份 CSV 数据文件,让 Agent 分析数据并生成可视化建议。使用 SDK 编写脚本完成此操作。
3. ⭐⭐⭐ 挑战题:设计一个多模态工作流——上传 UI 设计图,让 Agent 根据设计图生成对应的前端代码,然后截图对比生成结果与原始设计。记录完整的工具调用链。