AI Agent技术社区

目录

• 沙盒有些工具需要大模型的原因：
  • 关键原因：智能信息提取与过滤
    • 1. doc 工具需要 VLM(视觉语言模型)
    • 2. websearch 工具需要 LLM 总结
  • 总结
• docker对于vm启动的作用：
  • 🏗️ 三层架构
  • 🤔 为什么不直接运行VM，而要用Docker包装？
    • 1. 环境隔离与一致性 🔒
    • 2. 简化部署与分发 📦
    • 3. 硬件加速支持 ⚡
    • 4. 资源管理与并发 🎯
    • 5. 跨平台兼容性 🌍
    • 6. 快照与状态管理 💾
  • 🎭 类比理解
  • 📊 对比方案
• 各个成熟的配置所需要的准备
  • 通用准备(5 类都需要)
  • 1) RAG(RAGAgent)要准备什么
  • 2) MM-Doc(DocDancer)要准备什么
  • 3) DeepResearch(WebAgent)要准备什么
  • 4) Text2SQL 要准备什么
  • 5) Data Analysis(DSAgent，CSV/表格分析)要准备什么

沙盒有些工具需要大模型的原因：

关键原因：智能信息提取与过滤

沙盒虽然是工作环境，但它提供的不是被动的原始数据，而是智能化的工具服务。

1. doc 工具需要 VLM(视觉语言模型)

查看 doc_tool.py 的 ReadTool 实现：

核心功能：

• 文档通常包含多模态内容：文本、图片、表格等
• 当 Agent 调用 doc:read 时，会传入一个 goal(用户目标)
• VLM 的作用是根据 goal 从文档中智能提取相关信息

具体流程：

# 构造包含文本和图片的消息
messages.append({
    'role': 'user', 
    'content': [
        {"type": "image_url", "image_url": {...}},  # 文档中的图片
        {"type": "text", "text": GET_USEFUL_INFO_PROMPT.format(
            document_content=section_text, 
            goal=goal  # 用户目标
        )}
    ]
})

# VLM 分析并返回结构化信息
useful_info = vlm_client.get_useful_info(section_id, goal, messages)

VLM 会返回：

• rational: 推理过程
• evidence: 从文本和图像中提取的证据
• summary: 针对 goal 的总结

为什么不直接返回文档原文？

• 文档可能很长，包含大量无关信息
• 需要理解图片和表格中的视觉信息
• 需要根据任务目标进行智能筛选和推理

2. websearch 工具需要 LLM 总结

查看 websearch.py 的 LLMSummarizer：

def summarize(self, content: str, goal: str, url: str) -> str:
    prompt = f"""Based on the goal: "{goal}"
    
Please summarize the following content from {url}, 
focusing only on information relevant to the goal...
"""

核心问题：

• 网页内容往往冗长且包含大量无关信息(广告、导航、评论等)
• 如果直接返回完整网页内容，会：
  • 浪费 Agent 的上下文窗口
  • 降低 Agent 决策效率
  • 增加噪音干扰

LLM 的作用：

• 根据 goal 过滤无关内容
• 提取与任务相关的关键信息
• 生成简洁、针对性的摘要

总结

沙盒服务器的设计理念是：提供智能化的工具，而非被动的数据管道

工具层面	传统方案	沙盒方案(需要模型)
doc:read	返回文档原文	VLM 根据 goal 提取相关信息(含图片理解)
web:visit	返回完整网页 HTML	LLM 根据 goal 总结关键内容

这样做的好处：

1. 减轻 Agent 负担：Agent 收到的是高质量、相关性强的信息
2. 提高效率：避免 Agent 处理大量无关内容
3. 支持多模态：VLM 可以理解文档中的图片、表格
4. 上下文优化：只返回必要信息，节省 token

所以沙盒不仅仅是"环境"，更是一个智能中间层，在 Agent 和原始数据之间进行智能处理。

---

docker对于vm启动的作用：

根据我对代码的分析，我可以清楚地解释为什么agentflow使用Docker来启动VM。这个架构实际上有三层结构：

🏗️ 三层架构

宿主机 (你的物理机器)
  └─ Docker容器 (happysixd/osworld-docker)
       └─ QEMU虚拟机 (运行完整的Ubuntu/Windows系统)

🤔 为什么不直接运行VM，而要用Docker包装？

1. 环境隔离与一致性 🔒

Docker容器预先配置好了运行QEMU虚拟机所需的所有依赖：

• QEMU hypervisor及其配置
• VNC服务器 (用于图形界面访问)
• 各种网络和存储驱动
• Python服务器 (提供API接口)

你只需要 docker pull happysixd/osworld-docker 就能获得完整的运行环境，不需要手动安装配置QEMU、VNC、KVM等复杂组件。

2. 简化部署与分发 📦

从代码可以看到：

self.container = self.client.containers.run(
    "happysixd/osworld-docker",  # 统一的Docker镜像
    volumes={
        path_to_vm: {
            "bind": "/System.qcow2",  # 只需挂载VM磁盘镜像
            "mode": "ro"
        }
    },
    ...
)

你不需要担心：

• ✅ QEMU版本兼容性
• ✅ 系统库依赖
• ✅ 配置文件路径
• ✅ 启动参数

都被Docker镜像标准化了！

3. 硬件加速支持 ⚡

代码会检测KVM支持并自动配置：

if os.path.exists("/dev/kvm"):
    devices.append("/dev/kvm")  # 将宿主机的KVM设备传递给容器
    logger.info("KVM device found, using hardware acceleration")

Docker可以透传硬件设备(如 kvm)到容器内的QEMU，让VM获得接近原生的性能。

4. 资源管理与并发 🎯

看代码中的端口管理：

# 动态分配端口，支持多个VM同时运行
self.vnc_port = self._get_available_port(8006)
self.server_port = self._get_available_port(5000)
self.chromium_port = self._get_available_port(9222)
self.vlc_port = self._get_available_port(8080)

Docker让你可以：

• 在同一台机器上运行多个独立的VM实例
• 每个容器有自己的网络命名空间和端口映射
• 轻松清理和重启(container.stop() / container.remove())

5. 跨平台兼容性 🌍

代码支持Linux、Windows和macOS(通过Docker Desktop)：

if platform.system() == 'Windows':
    docker_path = r"C:\Program Files\Docker\Docker"
    os.environ["PATH"] += os.pathsep + docker_path

你在Windows上使用Docker Desktop也能运行Linux VM！

6. 快照与状态管理 💾

VM镜像(qcow2文件)以只读方式挂载：

volumes={
    os.path.abspath(path_to_vm): {
        "bind": "/System.qcow2",
        "mode": "ro"  # 只读，保护原镜像
    },
    "/tmp/qemu_storage": {
        "bind": "/storage",
        "mode": "rw"  # QEMU的overlay存储
    }
}

这样：

• 原始VM镜像永不污染
• 每次启动都是干净状态
• 支持长时间录屏(存储在宿主机磁盘)

🎭 类比理解

把Docker想象成一个便携式游戏主机：

• 🎮 Docker容器 = 游戏主机(配好了所有设置)
• 💿 qcow2镜像 = 游戏光盘(VM系统)
• 🖥️ 宿主机 = 你的桌子

你只需要：

1. 买一台标准的游戏主机(pull Docker镜像)
2. 插入游戏光盘(挂载qcow2)
3. 开机玩(container.run())

而不需要自己组装主机、调试硬件驱动！

📊 对比方案

方案	复杂度	可移植性	多实例支持	资源隔离
直接运行QEMU	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐	⭐
Docker + QEMU	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
VMware/VirtualBox	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐

总结：AgentFlow使用Docker不是为了"虚拟化"(那是QEMU做的)，而是为了打包运行环境、简化部署和支持大规模并发！

但是这里直接启动的话，可能会出现vm启动失败的情况，似乎只是资源紧张的问题，多重新启动几遍即可

各个成熟的配置所需要的准备

下面按 AgentFlow 仓库里对应的 5 个示例 Agent 来回答(术语映射：RAG→RAGAgent，MM-Doc→DocDancer，DeepResearch→WebAgent，Text2SQL→Text2SQL，Data Analysis→DSAgent)。AgentFlow 的这些环境，合成数据通常就是产出 synthesized_qa.jsonl + trajectories.jsonl 这类 QA+轨迹数据。 ([GitHub][1])

---

通用准备(5 类都需要)

• AgentFlow 安装好(pip install -e . 这种方式即可)。([GitHub][2])
• OpenAI-compatible LLM 的 Key / Base URL(用于合成阶段的 agent 推理与 QA 生成)。([GitHub][3])
• Seed(JSONL，一行一个 JSON)：每种环境都有自己的 seeds/.../seeds.jsonl 格式与关键字段。([GitHub][2])

---

1) RAG(RAGAgent)要准备什么

1. 本地 RAG 检索资源(三件套)：

   • RAG_EMBEDDING_MODEL_PATH：E5 类 embedding 模型本地路径
   • RAG_INDEX_PATH：FAISS index 文件路径
   • RAG_CORPUS_PATH：语料 corpus 的 JSONL 路径
     (可选：大语料可带 offset 文件加速随机读取) ([GitHub][2])

2. RAG seeds：seeds/rag/seeds.jsonl，通常是“主题/实体”作为起点：{"content": "Python programming language", "kwargs": {}} ([GitHub][2])

---

2) MM-Doc(DocDancer)要准备什么

1. 待处理的 PDF 文档(你的“知识源”是 PDF 本身)。

2. PDF 预处理产物(关键！)：seed 里要求放 outline.xml 的内容(XML 字符串)+ 预处理后文档目录 seed_path。([GitHub][4])

   • 预处理流程在仓库的 projects/docdancer/PDF_preprocess：包含 PDF 抽取、结构化处理、生成 outline 等步骤。([GitHub][5])

3. 两类模型/服务的 Key：

   • LLM key(合成/推理)
   • VLM key(doc_read 需要视觉语言模型读图+版面) ([GitHub][4])

---

3) DeepResearch(WebAgent)要准备什么

1. 联网搜索与网页抽取的第三方 Key(sandbox 里用)：

   • Serper API Key(Google 搜索)
   • Jina API Key(网页内容抽取)
   • 以及 LLM key ([GitHub][6])

2. Web seeds：seeds/web/seeds.jsonl，通常是“主题/实体”起点：{"content": "Machine learning", "kwargs": {}} ([GitHub][6])

---

4) Text2SQL 要准备什么

1. SQLite 数据库文件(.sqlite/.db)：你要么下载示例库、要么放入自己的库。([GitHub][7])
2. 把数据库注册到 sandbox 配置里：configs/sandbox-server/text2sql_config.json 的 resources.sql.config.databases 映射(db_id → 绝对路径)。([GitHub][7])
3. Text2SQL seeds：seeds/text2sql/seeds.jsonl，每条 seed 会指定目标库 + 重点表/探索模式，例如：{"content":"Database: chinook","kwargs":{"focus_tables":[...],"exploration_mode":"..."}} ([GitHub][7])
4. LLM key/base：用于生成问题、推理步骤与 SQL。([GitHub][7])

---

5) Data Analysis(DSAgent，CSV/表格分析)要准备什么

1. 本地 CSV 目录(你的“数据源”就是 CSV 文件夹)。
2. DS seeds：JSONL 里必须提供 kwargs.seed_path 指向 CSV 目录：{"content":"Analyze the data...","kwargs":{"seed_path":"seeds/ds/seed"}} ([GitHub][3])
3. LLM key/base：用于驱动工具调用与 QA 合成。([GitHub][3])