DeepSeek Harness: 多模态支持

最后更新:2026-08-31

文字只是 Agent 理解世界的一种方式——图片、音频、视频才是真实世界的语言。DSH 的多模态支持让 Agent 不只"读代码",还能"看界面""听反馈""观视频",极大扩展了 Agent 的感知边界。

💡 提示:多模态是 DSH 的 developer preview 特性,功能持续迭代中。当前最稳定的是图像输入,音频和视频支持仍在完善。

📋 前置知识:已完成 06-tools.md,了解工具系统基础

1. 你将学到


2. 多模态架构概览

多模态管线架构

(1) 多模态数据流

100%
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]                                    │
└───────────────────────────────────────────┘

支持的操作:

(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) 视频输入(实验性)

视频处理采用逐帧提取策略:

100%
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) 支持的文档格式

格式 解析方式 输出
PDF 文本提取 + 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 可以将多模态输入与工具调用结合:

100%
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,准确率较低。 ---

📖 小节


📝 作业

1. ⭐ 基础题:在 Web UI 中上传一张 UI 截图,让 Agent 描述截图中的内容。记录 Agent 的分析结果和使用的工具。

2. ⭐⭐ 进阶题:上传一份 CSV 数据文件,让 Agent 分析数据并生成可视化建议。使用 SDK 编写脚本完成此操作。

3. ⭐⭐⭐ 挑战题:设计一个多模态工作流——上传 UI 设计图,让 Agent 根据设计图生成对应的前端代码,然后截图对比生成结果与原始设计。记录完整的工具调用链。

Web-Tutorial.com

Web-Tutorial 技术团队

由多位开发者共同维护的编程教程平台。每篇教程由对应领域的开发者编写和审核,确保内容准确可靠。如发现任何问题,欢迎向我们反馈。

100%

🙏 帮我们做得更好

我们是刚上线的编程教程站,几个人的小团队,精力有限。页面虽经检查,难免还有疏漏——链接失效、排版错乱、内容有误、语言生硬……

如果您发现了,麻烦告诉我们,我们会在收到反馈后第一时间进行修复,再次感谢您的光临 🙏