原则</th>	说明</th></tr></thead>
生成与人工治理分离</strong></td>	模型自动生成，业务由人编排与审阅，不混用。</td></tr>
从最小可用体开始</strong></td>	用真实反馈驱动人体工学优化。</td></tr>
Golden Test</strong></td>	捕获/回放请求与响应，作为回归与审计基线。</td></tr>
上下文拣选与预算</strong></td>	只喂必要上下文，小而准、可复现。</td></tr> </tbody></table> 规范给 AI 以边界；AI 让规范鲜活起来。</p> 责任感：为什么我敢对 AI 写的代码负责我在 PR 里的说明</a> </h2> 这段说明最早见于 @xuanwo</a> 的 PR。我之前没有这样写，但我愿意采用这种方式——因为我对结果负责。在这个 SDK 的工作中我大量使用了 AI；边界与质量由我把关</strong>：</p> This PR was primarily authored with GPT-5-Codex and hand-reviewed by me. I’m responsible for every change that lands here.</strong></p> </blockquote> 这不是“炫 AI”，而是结果负责的声明</strong>。</p> 结语：速度与轨道— PsiACE</strong> （GitHub</a> · Apache OpenDAL PMC Member</a>）</p> ACP：交互契约与 Python SDK 2025-09-08T00:00:00+00:00 TL;DR </a> </h2> ACP 解决了什么</a> </h2> ACP 不只是“一条管道”，它规定：</p> 传输层用 JSON-RPC，支持流式更新；</li> 会话生命周期（new/load/prompt/cancel）清晰；</li> 内容块支持文本、图片、音频、资源链接等；</li> 工具调用与更新（tool_call</code> / tool_call_update</code>）格式统一；</li> 文件读写、任务计划、状态同步都有规范字段。</li> </ul> 换句话说，宿主（如 Zed）与智能体之间的 UX 语义不再每家重造，体验可以搬家。</p> 与其他标准的关系</a> </h2> AG-UI</strong>：同样关注交互层，部分语义重合，可能会出现“互转/共存”的场景。</li> MCP</strong>：负责工具和资源接入，适合与 ACP 搭配使用（工具能力来自 MCP，交互流程由 ACP 承载）。</li> A2A</strong>：聚焦智能体之间的通信，后续也可能与 ACP 对接。</li> </ul> Zed 的视角</a> </h2> 使用者：可以把 Claude Code、Gemini CLI、内部 Agent 统统接进编辑器，享受一致的流式体验和工具栏。</li> 开发者：写一次 ACP，就能跑在任何支持它的宿主上，减少重复 glue code。</li> 平台：通过协议锁定体验，生态统一，支持成本下降。</li> </ul> Python SDK 提供了什么</a> </h2> 安装：</p> pip</span></span> install agent-client-protocol</span> </span></code></pre> 功能：</p> Pydantic v2 模型：schema 都有类型提示；</li> AgentSideConnection</code> / ClientSideConnection</code>：分别处理智能体端与客户端；</li> stdio helper：适合 CLI/本地进程场景；</li> 与官方 schema 对齐，严格校验。</li> </ul> 最小 Echo Agent</a> </h3> import</span> asyncio</span></span></span> </span>from</span></span> acp</span></span> import</span></span></span></span></span> Agent</span>,</span> AgentSideConnection</span>,</span> stdio_streams</span></span> </span>from</span></span> acp</span></span> import</span></span></span></span></span> InitializeRequest</span>,</span> InitializeResponse</span>,</span> NewSessionRequest</span>,</span> NewSessionResponse</span></span> </span>from</span></span> acp</span></span> import</span></span></span></span></span> PromptRequest</span>,</span> PromptResponse</span>,</span> AuthenticateRequest</span>,</span> LoadSessionRequest</span>,</span> CancelNotification</span></span> </span> </span>class</span></span> EchoAgent</span></span>(</span></span></span>Agent</span>)</span></span>:</span></span> </span> async</span> def</span></span> initialize</span></span></span>(</span></span>self</span>,</span> params</span></span>:</span> InitializeRequest</span></span></span>)</span></span> </span>-></span> InitializeResponse</span></span></span>:</span></span> </span> return</span> InitializeResponse</span></span></span></span>(</span>protocolVersion</span>=</span>params</span>.</span>protocolVersion</span></span>)</span></span> </span> </span> async</span> def</span></span> newSession</span></span></span>(</span></span>self</span>,</span> params</span></span>:</span> NewSessionRequest</span></span></span>)</span></span> </span>-></span> NewSessionResponse</span></span></span>:</span></span> </span> return</span> NewSessionResponse</span></span></span></span>(</span>sessionId</span>=</span>"</span></span></span>sess-1"</span></span></span>)</span></span> </span> </span> async</span> def</span></span> loadSession</span></span></span>(</span></span>self</span>,</span> params</span></span>:</span> LoadSessionRequest</span></span></span>)</span></span> </span>-></span> None</span></span>:</span></span> </span> return</span> None</span> </span> </span> async</span> def</span></span> authenticate</span></span></span>(</span></span>self</span>,</span> params</span></span>:</span> AuthenticateRequest</span></span></span>)</span></span> </span>-></span> None</span></span>:</span></span> </span> return</span> None</span> </span> </span> async</span> def</span></span> prompt</span></span></span>(</span></span>self</span>,</span> params</span></span>:</span> PromptRequest</span></span></span>)</span></span> </span>-></span> PromptResponse</span></span></span>:</span></span> </span> return</span> PromptResponse</span></span></span></span>(</span>stopReason</span>=</span>"</span></span></span>end_turn"</span></span></span>)</span></span> </span> </span> async</span> def</span></span> cancel</span></span></span>(</span></span>self</span>,</span> params</span></span>:</span> CancelNotification</span></span></span>)</span></span> </span>-></span> None</span></span>:</span></span> </span> return</span> None</span> </span> </span>async</span> def</span></span> main</span></span></span>(</span></span>)</span></span> </span>-></span> None</span></span>:</span></span> </span> reader</span></span>, writer</span></span> =</span> await</span> stdio_streams</span></span></span></span>(</span>)</span></span> </span> AgentSideConnection</span></span></span></span>(</span>lambda</span></span></span> _conn</span>:</span></span></span> EchoAgent</span></span></span></span>(</span>)</span></span></span>,</span> writer</span></span>,</span> reader</span></span>)</span></span> </span> await</span> asyncio</span></span>.</span></span>Event</span></span></span></span>(</span>)</span></span>.</span></span>wait</span></span></span></span>(</span>)</span></span> </span> </span>if</span> __name__</span></span> ==</span> "</span></span></span>__main__"</span></span></span>:</span></span> </span> asyncio</span></span>.</span></span>run</span></span></span></span>(</span>main</span></span></span></span>(</span>)</span></span>)</span></span> </span></code></pre> Zed 侧 settings.json</code>：</p> {</span> </span></span> </span>"</span>agent_servers"</span></span></span>:</span> </span>{</span> </span></span></span> </span>"</span>Echo Agent (Python)"</span></span></span>:</span> </span>{</span> </span></span></span></span> </span>"</span>command"</span></span></span>:</span> </span>"</span>/abs/path/to/python"</span></span>,</span> </span></span></span></span> </span>"</span>args"</span></span></span>:</span> </span>[</span>"</span>/abs/path/to/echo_agent.py"</span></span>]</span></span>,</span> </span></span></span></span> </span>"</span>env"</span></span></span>:</span> </span>{</span>}</span></span> </span></span></span></span> }</span></span> </span></span></span> }</span></span> </span></span>}</span></span> </span></code></pre> 打开命令面板输入 “dev: open acp logs” 可以调试序列化。</p> 接下来</a> </h2> 补充更多示例：工具调用、文件交互、计划同步；</li> 与 MCP 结合，做端到端 demo；</li> 观察协议演进，及时跟进 schema 变更。</li> </ul> ACP 代表的是“交互语义的标准化”。当智能体要进主流工作流时，拥有统一契约就像当年云原生时代的容器、服务网格一样重要。Python SDK 的目标，就是让这件事变得简单，让反馈闭环先跑起来，再慢慢打磨。</p> Agent 没有秘密可言 2025-08-14T00:00:00+00:00 我是 PsiACE。最近我的工作主要围绕 Agent 与 RAG 展开：少谈玄学，多把闭环跑通</strong>，多让系统说得清楚、跑得稳定、可被回放与切换。</p> </blockquote> TL;DR</a> </h2> Agent 不是新宗教</strong>。它依然是事件、队列、CRUD 的工程实践，再加一层模型协作。</li> 共用一条 EventBus，把 agent.</code> 与 huey.</code> 事件打通；每条事件立即打印；最后用 Cascade 树复盘因果与时间。</li> 单文件 Demo，打开即跑</strong>：先看事件，后看因果，最后看结果。</li> </ul> </p> 为什么写这个（以及为什么这么写）</a> </h2> 我不想再讨论"如何画出一个复杂的 Agent 架构图"。我更关心"如何让系统解释得清楚、失败得优雅、复盘得明白</strong>"。</li> 这篇文章附带一个单文件 Demo：共享总线、严格 ReACT、因果与时间合并呈现、即时可观测。开箱即用</strong>。</li> </ul> 我怎么做的</a> </h2> 核心设计原则</a> </h3> 共享 EventBus</strong>：Agent、ToolExecutor、Storage 都向同一条总线发事件。</li> 严格 ReACT</strong>：Thought → Action → Action Input → Observation → Final Answer。</li> 因果 + 时间</strong>：每轮用户输入推进 tick</code>；每次 Observation 再推进 tick</code>；Action → huey.* → Observation</code> 通过 parent-child 串起来。</li> 即时可观测</strong>：每条事件实时打印；最后用树形 Cascade Viewer 做分时复盘。</li> </ul> 事件流（概览）</a> </h3> </p> 这和"传统架构"有什么不同？</a> </h2> 没有不同</strong>：事件、队列、CRUD，本来就在；只是把模型作为协作者接了进来。</li> 也不浮夸</strong>：没有"智能"也不会失效的设计；它可靠、可解释，也更容易落地。</li> </ul> 极简骨架（节选）</a> </h2> Event-driven storage wrapper</a> </h3> class</span></span> EventureMemoryStorage</span></span>(</span></span></span>MemoryStorage</span>)</span></span>:</span></span> </span> def</span></span> __init__</span></span></span>(</span></span>self</span>,</span> event_bus</span></span>:</span> EventBus</span></span></span>)</span></span>:</span></span> </span> super</span></span></span></span>(</span>)</span></span>.</span></span>__init__</span></span></span></span>(</span>"</span></span></span>huey"</span></span></span>)</span></span> </span> self</span>.</span>bus</span></span> =</span> event_bus</span></span> </span> </span> def</span></span> enqueue</span></span></span>(</span></span>self</span>,</span> data</span>,</span> priority</span></span>=</span>None</span></span>)</span></span>:</span></span> </span> super</span></span></span></span>(</span>)</span></span>.</span></span>enqueue</span></span></span></span>(</span>data</span></span>,</span> priority</span>=</span>priority</span></span>)</span></span> </span> self</span>.</span>bus</span></span>.</span></span>publish</span></span></span></span>(</span>"</span></span></span>huey.queue.enqueue"</span></span></span>,</span> {</span> </span></span></span></span> </span>"</span></span></span>data"</span></span></span></span>:</span></span> </span>data</span></span></span>,</span> </span></span></span> </span>"</span></span></span>priority"</span></span></span></span>:</span></span> </span>priority</span></span> </span></span></span></span> }</span></span>)</span></span> </span></code></pre> Tool with self-description</a> </h3> def</span></span> tool_echo</span></span></span>(</span></span>params</span></span>:</span> dict</span></span></span>)</span></span> </span>-></span> dict</span></span></span>:</span></span> </span> """</span>Echo back text. Args: {"text": string} Returns: {"ok": bool, "echo": string}"""</span></span> </span> return</span> {</span></span>"</span></span></span>ok"</span></span></span></span>:</span></span> </span>True</span></span>,</span> </span>"</span></span></span>echo"</span></span></span></span>:</span></span> </span>str</span></span></span></span>(</span>params</span></span>.</span></span>get</span></span></span></span>(</span>"</span></span></span>text"</span></span></span>,</span> "</span></span></span>"</span></span></span>)</span></span>)</span></span></span>}</span></span> </span></code></pre> ReACT loop（核心思想）</a> </h3> while</span> True</span>:</span></span> </span> resp</span></span> =</span> client</span>.</span>chat</span>.</span>completions</span></span>.</span></span>create</span></span></span></span>(</span>model</span>=</span>model</span></span>,</span> messages</span>=</span>history</span></span>)</span></span> </span> assistant</span></span> =</span> resp</span>.</span>choices</span></span></span>[</span></span>0</span></span>]</span></span>.</span>message</span>.</span>content</span> or</span> "</span></span></span>"</span></span></span> </span> call</span></span> =</span> extract</span></span></span></span>(</span>assistant</span></span>)</span></span> </span> </span> if</span> call</span></span>:</span></span> </span> action_id</span></span> =</span> uuid4</span></span></span></span>(</span>)</span></span> </span> bus</span></span>.</span></span>publish</span></span></span></span>(</span>"</span></span></span>agent.action"</span></span></span>,</span> {</span></span>"</span></span></span>id"</span></span></span></span>:</span></span> </span>action_id</span></span></span>,</span> *</span>call</span></span>}</span></span>)</span></span> </span> #</span> wait for agent.observation(id==action_id) and append as Observation </span></span> continue</span> </span> </span> return</span> assistant</span></span> </span></code></pre> 我遵循的几个原则</a> </h2> 先闭环，后花活</strong>：先把"事件→队列→状态变化→ReACT"打通，再谈优化。</li> 因果与时间是工程的一等公民</strong>：tick 表达更新周期；parent-child 表达触发链。</li> 可观测性优先</strong>：当系统能解释自己，优化才有基础。</li> 可替换</strong>：总线稳定，后端可换（内存→Redis），模型可换（供应商/版本）。</li> </ul> 如何运行（单终端）</a> </h2> 代码位置</a> </h3> 请点击【阅读原文】跳转：</p> agent_has_no_secret.py</a></li> README.md</a></li> </ul> 运行步骤</a> </h3> 配置 .env</code>（OpenRouter 推荐；OpenAI 也可）</li> python agent_has_no_secret.py</code></li> </ol> 你将看到什么</a> </h3> 实时事件流</strong>：user.input</code>、agent.thought</code>、agent.action</code>、huey.data.</code>、agent.observation</code> …</li> 绿色的 Final Answer</strong> 面板</li> 按 tick 分组的树形 Cascade Viewer</strong>：在 agent.action</code> 下能看到 huey.data.</code> 与 agent.observation</code> 的父子层级</li> </ul> 写在最后</a> </h2> 我更钦佩能把东西"说清楚、跑起来</strong>"的工程师。Agent 没有秘密可言：</p> 先把闭环打通，再考虑花活；</li> 先让因果与代价可见，再谈"更聪明"。</li> </ul> Baby Steps: 用 Python 实现一个能自举的 Coding Agent 2025-07-16T00:00:00+00:00 Bub 的第一个 milestone：自动修类型注解。由 Moonshot K2 驱动</p> Bub:</strong> Successfully fixed the first mypy issue by adding the missing return type annotation -> None</code> to the __init__</code> method in src/bub/cli/render.py</code>, reducing the error count from 24 to 23.</p> </blockquote> 1. 为什么要自己造 Agent？</a> </h2> Coding Agent 现在已经是个红海赛道，市面上有不少优秀的产品，比如 yetone 的 avante.nvim、晋涛哥哥推荐的 AmpCode，还有许多团队在 PPT 中绘制宏伟蓝图。然而，Coding Agent 的“token 大力出奇迹”现象也很明显——动辄几十万 token 的消耗，真正有价值的部分却少之又少。这让我很好奇：如果自己动手造一个 Coding Agent，能不能找到更高效、更实用的解决方案？</p> 于是，我开始折腾一个叫 Bub 的 CLI 助手。它的目标很简单：做一个命令行下的实用助手，同时具备有限的自举能力。自举这个概念在编译器、操作系统领域早已不算新鲜，很多 Coding Agent 也喜欢宣传“AI 工程师贡献了多少代码”。我希望 Bub 能迈出自己的第一步，解决它自身代码中的第一个实际问题。</p> 2. 最小可用：先跑起来再说</a> </h2> 我的经验是，能跑起来的最小闭环最重要，别一上来就追求“完美架构”或者花太多时间做数据小偷。</p> Bub 的分层很简单：</p> Agent</strong>：主循环，负责 LLM 交互、工具调用、上下文管理。</li> Tool</strong>：每个工具一个类，参数用 Pydantic 校验。</li> ToolRegistry</strong>：注册所有工具，方便扩展。</li> CLI</strong>：Typer + Rich，命令行入口，支持展开中间状态。</li> </ul> Agent 的本质其实就是一个 while 循环。每次循环，Agent 会根据当前上下文判断是否需要调用工具，如果需要就调用，然后把工具的返回结果写回上下文。</p> 主循环核心代码</a> </h3> class</span></span> Agent</span></span>:</span></span> </span> def</span></span> chat</span></span></span>(</span></span>self</span>,</span> message</span></span>:</span> str</span></span></span>)</span></span> </span>-></span> str</span></span></span>:</span></span> </span> self</span>.</span>conversation_history</span></span>.</span></span>append</span></span></span></span>(</span>Message</span></span></span></span>(</span>role</span>=</span>"</span></span></span>user"</span></span></span>,</span> content</span>=</span>message</span></span>)</span></span>)</span></span> </span> while</span> True</span>:</span></span> </span> #</span> 构造上下文，历史消息+工具列表 </span></span> ...</span> </span> response</span></span> =</span> litellm</span></span>.</span></span>completion</span></span></span></span>(</span>...</span>)</span></span> </span> assistant_message</span></span> =</span> str</span></span></span></span>(</span>response</span>.</span>choices</span></span></span>[</span></span>0</span></span>]</span></span>.</span>message</span>.</span>content</span>)</span></span> </span> self</span>.</span>conversation_history</span></span>.</span></span>append</span></span></span></span>(</span>Message</span></span></span></span>(</span>role</span>=</span>"</span></span></span>assistant"</span></span></span>,</span> content</span>=</span>assistant_message</span></span>)</span></span>)</span></span> </span> tool_calls</span></span> =</span> self</span>.</span>tool_executor</span></span>.</span></span>extract_tool_calls</span></span></span></span>(</span>assistant_message</span></span>)</span></span> </span> if</span> tool_calls</span></span>:</span></span> </span> for</span> tool_call</span> in</span></span> tool_calls</span></span></span>:</span></span> </span> result</span></span> =</span> self</span>.</span>tool_executor</span></span>.</span></span>execute_tool</span></span></span></span>(</span>tool_call</span>.</span>name</span></span>,</span> </span>tool_call</span>.</span>parameters</span></span>)</span></span> </span> observation</span></span> =</span> f</span>"</span></span></span>Observation: </span>{</span>result</span></span>.</span></span>format_result</span></span></span></span>(</span>)</span></span></span></span>}</span></span>"</span></span></span> </span> self</span>.</span>conversation_history</span></span>.</span></span>append</span></span></span></span>(</span>Message</span></span></span></span>(</span>role</span>=</span>"</span></span></span>user"</span></span></span>,</span> content</span>=</span>observation</span></span>)</span></span>)</span></span> </span> continue</span> </span> else</span>:</span></span> </span> return</span> assistant_message</span></span> </span></code></pre> 踩过的坑：</strong></p> 没有捕获，LLM 输出格式一变就死循环</li> 工具参数没校验，LLM 乱传参数直接崩</li> Observation 反馈太长或缺乏有效信息，LLM 理解困难</li> </ul> 3. 工具定义：扩展 LLM 的能力</a> </h2> 工具是 LLM 和外部世界的桥梁，定义得好，模型才能真正“动手”。我的做法是：</p> 工具参数全部用 Pydantic 校验，类型不对直接拒绝。</li> 命令行工具有黑名单（比如 rm</code>、del</code>），遇到危险命令直接报错。</li> 工具执行结果结构化返回，别让 LLM 猜。</li> 操作命令行工具时，stdout 和 stderr 都很重要，不能只给 exit code。</li> 工具之间要有明确边界，避免混淆。</li> </ul> class</span></span> RunCommandTool</span></span>(</span></span></span>Tool</span>)</span></span>:</span></span> </span> DANGEROUS_COMMANDS</span></span> =</span> {</span>"</span></span></span>rm"</span></span></span>,</span> "</span></span></span>del"</span></span></span>}</span></span> </span> def</span></span> _validate_command</span></span></span>(</span></span>self</span>,</span> base_cmd</span></span>:</span> str</span></span></span>)</span></span> </span>-></span> Optional</span></span></span>[</span></span>str</span></span></span>]</span></span></span>:</span></span> </span> if</span> base_cmd</span></span> in</span> self</span>.</span>DANGEROUS_COMMANDS</span></span>:</span></span> </span> return</span> f</span>"</span></span></span>Dangerous command blocked: </span>{</span>base_cmd</span></span></span></span>}</span></span>"</span></span></span> </span> def</span></span> execute</span></span></span>(</span></span>self</span>,</span> context</span></span>:</span> Context</span></span></span>)</span></span> </span>-></span> ToolResult</span></span></span>:</span></span> </span> #</span> 校验命令，执行并返回结果 </span></span></code></pre> 4. Prompt 设计：让 LLM 按套路出牌</a> </h2> 组织良好的提示词能显著提升 LLM 的输出质量。对于 Coding Agent 来说尤其重要，因为 LLM 的输出格式很容易失控。</p> 我的经验：</p> Prompt 里要列出所有工具和参数 schema。</li> 多给几个调用示例，覆盖常见用法。</li> Observation 反馈要简洁，别堆无用信息。</li> </ul> Bub 的 ReAct Prompt 结构：</strong></p> You are an AI assistant with access to tools. When you need to use a tool, follow this format: </span> </span>Thought: ... </span>Action: run_command </span>Action Input: {"command": "ls"} </span>Observation: <output> </span>... </span>Final Answer: <your answer> </span></code></pre> ReAct 的好处是简单直接，容易落地，虽然 token 消耗大，但能快速试错、跨模型迁移。</p> 5. milestone：自动修类型注解</a> </h2> 定义好 Agent Loop、工具和 Prompt 后，Bub 的第一个 milestone 就是自动修复了一个 mypy 报错。</p> 比如：</p> -</span> def __init__(self): </span></span>-</span> self.console = Console() </span></span>-</span> self._show_debug = False </span></span>+</span> def __init__(self) -> None: </span></span>+</span> self.console: Console = Console() </span></span>+</span> self._show_debug: bool = False </span></span></code></pre> 实际的 Agent Loop：</p> 只让 agent 改类型注解、格式化、重命名，别让它碰复杂逻辑。</li> 先用命令行工具执行 mypy</code>，拿到报错信息。</li> 让 agent 生成修复建议，再用 file edit 工具应用到代码。</li> 修完自动再跑一次 mypy，确保没新问题。</li> </ul> 踩过的坑：</strong></p> 模型对代码上下文理解有限，经常修错。</li> 不验证，bug 越修越多。</li> </ul> 6. 进阶玩法与工程自查</a> </h2> 随着功能扩展，踩的坑也越来越多。我的一些经验：</p> 工具扩展时，建议单一职责，参数 schema 明确。</li> 长对话要截断或摘要，别让 LLM 超窗。</li> 生产环境建议沙箱/虚拟机，命令行工具默认禁危险命令。</li> LLM 输出格式不稳时要有 fallback 兜底。</li> </ul> 7. 总结</a> </h2> Bub 还在早期，但已经能帮我自动修 bug、跑命令、读写文件。我希望这只是一个开始，然后得到更多有意思的反馈。</p> </p> 参考资料</a> </h3> How to Build an Agent (ampcode)</a></li> Tiny Agents: Building LLM-Powered Agents from Scratch (HuggingFace)</a></li> Bub: Bub it. Build it.</a></li> </ul> 让 LlamaIndex 接上 Cloudflare AI Gateway 2025-07-11T00:00:00+00:00 为什么折腾这个</a> </h2> 单供应商的 LLM 太脆弱：OpenAI 宕机、Anthropic 限流，就等于业务停摆。Cloudflare AI Gateway 给了一个诱人的承诺：</p> 多家模型的统一入口；</li> 内置缓存、限流、熔断；</li> 请求失败自动切换。</li> </ul> 问题是，LlamaIndex 的 LLM 调用直接命中各家 API，没法自适应 Gateway。我需要一个中间层，让原有代码不改，直接享受多云编排。</p> 解决方案</a> </h2> 写了一个轻量 wrapper：</p> from</span></span> llama_index</span>.</span>llms</span>.</span>cloudflare_ai_gateway</span></span> import</span></span></span></span></span> CloudflareAIGateway</span></span> </span>from</span></span> llama_index</span>.</span>llms</span>.</span>openai</span></span> import</span></span></span></span></span> OpenAI</span></span> </span>from</span></span> llama_index</span>.</span>llms</span>.</span>anthropic</span></span> import</span></span></span></span></span> Anthropic</span></span> </span> </span>openai_llm</span></span> =</span> OpenAI</span></span></span></span>(</span>model</span>=</span>"</span></span></span>gpt-4o-mini"</span></span></span>,</span> api_key</span>=</span>"</span></span></span>your-key"</span></span></span>)</span></span> </span>anthropic_llm</span></span> =</span> Anthropic</span></span></span></span>(</span>model</span>=</span>"</span></span></span>claude-3-5-sonnet"</span></span></span>,</span> api_key</span>=</span>"</span></span></span>your-key"</span></span></span>)</span></span> </span> </span>gateway_llm</span></span> =</span> CloudflareAIGateway</span></span></span></span>(</span> </span></span> llms</span>=</span>[</span>openai_llm</span></span>,</span> anthropic_llm</span></span>]</span></span>,</span> </span></span> account_id</span>=</span>"</span></span></span>your-cloudflare-account-id"</span></span></span>,</span> </span></span> gateway</span>=</span>"</span></span></span>your-gateway-name"</span></span></span>,</span> </span></span> api_key</span>=</span>"</span></span></span>your-cloudflare-api-key"</span></span></span>,</span> </span></span>)</span></span> </span> </span>resp</span></span> =</span> gateway_llm</span></span>.</span></span>chat</span></span></span></span>(</span>[</span>ChatMessage</span></span></span></span>(</span>role</span>=</span>"</span></span></span>user"</span></span></span>,</span> content</span>=</span>"</span></span></span>2 + 2 = ?"</span></span></span>)</span></span>]</span></span>)</span></span> </span></code></pre> 作用就是：截住 LlamaIndex 发出的请求，改写为 Cloudflare 期待的格式，处理返回值。原始业务代码不用动。</p> 能做什么</a> </h2> 顺序尝试多个模型，失败自动换下一个；</li> 支持 Cloudflare 的流式接口、异步调用；</li> 统一注入鉴权、重试、日志；</li> 经过实测的模型：OpenAI、Anthropic；</li> 理论兼容：Google AI Studio、DeepSeek、Grok、Azure OpenAI、Perplexity、Replicate 等。</li> </ul> 如何体验</a> </h2> PR 在提审（#19395</a>），不过代码已经能跑：</p> git</span></span> clone <</span>repo></span> </span></span>cd</span></span> llama-index-llms-cloudflare-ai-gateway</span> </span>pip</span></span> install -</span>e</span> .</span> </span> </span>export</span> OPENAI_API_KEY</span>=</span>...</span></span> </span>export</span> ANTHROPIC_API_KEY</span>=</span>...</span></span> </span>export</span> CLOUDFLARE_ACCOUNT_ID</span>=</span>...</span></span> </span>export</span> CLOUDFLARE_API_KEY</span>=</span>...</span></span> </span>export</span> CLOUDFLARE_GATEWAY</span>=</span>...</span></span> </span> </span>uv</span></span> run pytest tests/</span> </span></code></pre> 注意事项</a> </h2> Cloudflare 虽然提供 OpenAI 兼容接口，但做中间层能解锁更多功能（自定义头、特定路由、日志追踪）。</li> 多模型编排别忘了考虑一致性：模型切换后回答风格可能不同，需要在应用层消化。</li> 缓存命中率很依赖 prompt 规范，必要时结合 embedding 去重。</li> </ul> 这个封装的意义不在于“又造了个轮子”，而是告诉你：在 LlamaIndex 体系里，替换底层 LLM 客户端是很容易的。运维侧想要多云容灾、成本优化，只需要写一个薄薄的适配层。</p> 用 WebAssembly 为 Code Agent 范式构建安全沙箱 2025-07-08T00:00:00+00:00 Code Agent（代码代理范式）的能力令人惊叹，但安全性问题同样令人担忧。在我测试第一个 Code Agent 时，它很快就尝试安装包、访问环境变量，甚至想要读取系统文件。我们需要一个真正安全的执行环境。</strong></p> 安全挑战</a> </h2> 代码执行型 AI 代理（Code Agent 范式）确实能完成很多任务——数据分析、数学计算、代码调试。但它们缺乏对系统边界的认知，可能带来严重的安全风险。</p> 典型的安全威胁场景：</p> 权限越界</strong>：尝试访问 /etc/passwd</code>、系统环境变量</li> 恶意包安装</strong>：从被污染的 PyPI 源安装恶意包</li> 资源耗尽</strong>：无限循环、内存泄漏导致系统崩溃</li> 网络攻击</strong>：发起 DDoS、端口扫描等恶意行为</li> </ul> 像 Hugging Face smolagents</a> 之类的项目已经意识到了这个问题，提供了多种执行器选项来平衡功能性和安全性。</p> WebAssembly 的安全优势</a> </h2> WebAssembly 的核心价值不在于性能，而在于原生安全设计</strong>。作为从浏览器安全模型发展而来的技术，WASM 提供了：</p> 能力安全模型</strong>：基于最小权限原则，只能访问明确授权的资源</li> 细粒度资源控制</strong>：精确监控 CPU 使用、内存分配、网络访问</li> 执行确定性</strong>：相同的输入总是产生相同的输出，便于审计</li> 语言无关性</strong>：支持多种编程语言的安全执行</li> </ol> Simon Willison 在他的 TIL 文章</a> 中详细探讨了这个方案，Hacker News 社区也有深入讨论</a>。</p> 虽然 Hugging Face smolagents</a> 已经提供了基于 Pyodide 和 Deno 的 WasmExecutor</code>，但我想探索一个基于 wasmtime 的本地执行方案，看看有什么不同的技术权衡。</p> 技术实现</a> </h2> 基于 wasmtime-py 和 VMware 的 Python WASM 运行时，我实现了一个简单的沙箱执行器：</p> from</span></span> wasmtime_executor</span></span> import</span></span></span></span></span> WasmtimePythonExecutor</span></span> </span>from</span></span> smolagents</span></span> import</span></span></span></span></span> CodeAgent</span>,</span> InferenceClientModel</span></span> </span> </span>class</span></span> WasmtimeCodeAgent</span></span>(</span></span></span>CodeAgent</span>)</span></span>:</span></span> </span> def</span></span> create_python_executor</span></span></span>(</span></span>self</span>)</span></span>:</span></span> </span> return</span> WasmtimePythonExecutor</span></span></span></span>(</span> </span></span> additional_authorized_imports</span>=</span>self</span>.</span>additional_authorized_imports</span></span>,</span> </span></span> max_print_outputs_length</span>=</span>self</span>.</span>max_print_outputs_length</span></span>,</span> </span></span> </span>self</span>.</span>executor_kwargs</span></span>,</span> </span></span> )</span></span> </span> </span>agent</span></span> =</span> WasmtimeCodeAgent</span></span></span></span>(</span> </span></span> tools</span>=</span>[</span>]</span></span>,</span> </span></span> model</span>=</span>InferenceClientModel</span></span></span></span>(</span>)</span></span>,</span> </span></span> additional_authorized_imports</span>=</span>[</span>"</span></span></span>math"</span></span></span>,</span> "</span></span></span>json"</span></span></span>]</span></span>,</span> </span></span>)</span></span> </span> </span>result</span></span> =</span> agent</span></span>.</span></span>run</span></span></span></span>(</span>"</span></span></span>Calculate the square root of 125"</span></span></span>)</span></span> </span></code></pre> 核心实现思路：利用 VMware 提供的 Python WASM 二进制文件，通过 wasmtime-py 进行运行时管理，并实现与 smolagents 的兼容层。关键的技术差异在于本地执行</strong>，避免了对外部 Deno 运行时的依赖。</p> 技术评估</a> </h2> 优势方面：</strong></p> 与 smolagents 框架的无缝集成</li> 基础 Python 操作的良好支持</li> 完善的错误处理和异常捕获</li> 执行状态的有效隔离和持久化</li> 本地化部署</strong>，减少网络依赖</li> </ul> 技术权衡：</strong></p> 安全隔离 vs Python 生态系统限制</li> 执行安全性 vs 性能开销</li> 确定性执行 vs 配置复杂性</li> 本地控制</strong> vs 远程服务调用</li> </ul> 生产就绪性</a> </h2> 当前状态：实验性项目</strong>。这个实现主要用于概念验证和技术探索。</p> 生产环境部署需要解决的关键问题：</p> 资源限制和配额管理</li> 包依赖管理和安全扫描</li> 性能优化和缓存策略</li> 完整的审计日志和监控</li> 安全漏洞的持续评估</li> </ul> 但对于技术研究、原型验证、理解安全边界？这个实现提供了很好的起点。</p> 技术价值</a> </h2> 这个项目的真正价值不在于具体的实现代码，而在于证明了Code Agent 范式存在多种安全沙箱方案</strong>。虽然 smolagents 提供了基于 Pyodide 的 Deno 沙箱，wasmtime 为本地执行提供了另一种技术选择。开发者可以基于现有的代理框架，添加安全边界，保持功能完整性，同时探索不同的技术权衡。</p> 进一步探索</a> </h2> 完整的实现代码和详细文档在我的 Wasmtime 执行器项目</a> 中。代码虽然粗糙，但功能完整。欢迎克隆、测试、改进。</p> 理解 Code Agent 范式安全挑战的最佳方式就是动手实践。即使是简单的概念验证项目，也能带来深刻的技术洞察。</p> 参考资料</a> </h2> Hugging Face smolagents</a></li> Wasmtime 执行器项目</a></li> Simon Willison 的 WASM Python 沙箱</a></li> VMware WebAssembly 语言运行时</a></li> </ul> 当 RAG 遇上编程助手 2025-06-18T00:00:00+00:00 我的日常工作是和 RAG 打交道，最近 Coding Agent 大热，Claude Code 、Cursor 这样的工具已经成为了研发必备的效率神器，于是尝试调研和学习了一下，抛砖引玉。</p> </blockquote> TL;DR</a> </h2> Coding Agent 中其实不少环节都可以用到 RAG（检索增强生成），把"查资料"和"写代码"这两件事结合起来。具体来说：</p> 理解你想干什么</strong>：分析需求，找到相关代码和文档</li> 快速定位文件</strong>：在大项目里找到关键模块</li> 写出合适的代码</strong>：基于实际情况和最佳实践</li> 帮你调试</strong>：分析错误，搜索解决方案</li> </ul> 说白了，就是让编程助手从"代码生成器"变成真正的"软件工程师"。</p> 写代码的真实痛点</a> </h2> 作为一个软件工程师，大部分时间我们都在干这些事：</p> 搞懂一个巨大项目是怎么工作的</li> 在几百个文件里找到那个该死的模块</li> 看着莫名其妙的报错发呆</li> 学新框架新工具</li> </ul> </p> 这些事情真的很烦，也很费时间。Coding Agent 应该帮我们处理这些重复劳动，让我们可以自由表达自己的想法。假如你的 “编程搭子” 还不够聪明，理解不了你的代码，找不到对的信息，那几乎只会搞砸一切，更别说帮你调试了。</p> Coding Agent 到底是什么</a> </h2> 想象一下，你要做一个从没做过的功能。通常你会这样：</p> 先 Google 找例子</li> 翻框架文档</li> 在自己项目里搜类似的代码</li> 上 StackOverflow 看看别人怎么解决的</li> </ul> Coding Agent 就是一个可以自主执行这些动作的智能体，或者说把这个过程自动化了。它不仅可以充当搜索引擎进行学习，还能把找到的信息组合起来，帮你写代码。</p> 原理其实很简单：</p> 检索（Retrieval）</strong>：找相关的东西——代码、文档、问答</li> 生成（Generation）</strong>：用这些信息写出新的代码或解决方案</li> </ol> 就这两步，但效果比单纯的代码生成器强多了。</p> 当然，为了让一切更加顺利，还需要添加反馈机制。根据调试信息优化并进行修正。</p> </blockquote> RAG 怎么让编程助手变聪明</a> </h2> 结合 RAG，编程助手就能处理我们平时遇到的各种问题了。</p> </p> 整个过程大概是这样的：</p> 1. 搞清楚你要干什么</strong></a> </h3> 你说"给 API 加个用户认证"，助手得先理解：</p> 要 JWT、OAuth 还是别的方案？</li> 现有代码哪里需要改？</li> 你用的什么框架？</li> </ul> 然后开始工作——去翻文档找例子，把你的需求搞清楚。</p> 2. 收集相关资料</strong></a> </h3> 然后就是搜集阶段，像个勤快的实习生一样，到处找：</p> 官方文档</strong>：框架的使用指南</li> 代码例子</strong>：你项目里或者开源项目的类似实现</li> 社区问答</strong>：StackOverflow、GitHub 上的讨论</li> 最佳实践</strong>：编码规范和安全建议</li> </ul> 把这些都混在一起，就是传说中的"知识汤"。</p> 3. 写代码并测试</strong></a> </h3> 有了这些资料，助手就能写出比较靠谱的代码了。但它不会直接给你，而是先在沙箱里跑一遍：</p> 看看有没有明显的错误</li> 确认确实能解决你的问题</li> 有问题的话马上调整</li> </ul> 4. 处理成功和失败</strong></a> </h3> 代码跑通了当然好，但如果出错了，它不会放弃：</p> 分析错误信息</li> 去找类似问题的解决方案</li> 用新信息再试一遍</li> </ul> 这个循环让 Coding Agent 变得靠谱多了。</p> 5. 交付成果</strong></a> </h3> 最后，助手会把完整的解决方案给你——不只是代码，还有说明文档。</p> 最大的坑：什么时候去查资料？</a> </h2> 用 RAG 有个很关键的问题：什么时候该去查资料</strong>？</p> 太早查可能漏掉重要信息，太晚查又会拖慢速度。我觉得这样比较合理：</p> 通用的东西（框架文档、编码规范）提前准备好</li> 具体问题（调试、特殊需求）现查现用</li> </ul> 这样既不会太慢，也不会出错。</p> 什么信息该存，什么该丢</a> </h2> 不是所有信息都一样重要。有些东西（比如框架规则）得一直记着，有些（比如这次运行的日志）用完就可以扔了。</p> </p> 这样处理可能会是一个不错的路线：</p> 知识类型</strong></th> 怎么存</strong></th> 怎么找</strong></th></tr></thead> 编码规范</td> 一直存着</td> 知识图谱快速查找</td></tr> 文档教程</td> 按版本存</td> 语义搜索相关部分 + 代码结构映射</td></tr> 问答和代码库</td> 先临时后永久</td> API 查询 + 缓存</td></tr> 运行时反馈</td> 临时存储</td> 即时检索和更新</td></tr> </tbody></table> 这样既不会太慢，也不会占太多空间。</p> 执行的上下文越长，无效的信息越多，也需要及时压缩和截断，保留真正有效的部分。</p> </blockquote> 想试试的话，从简单开始</a> </h2> 如果你也想写个编程助手，但不想搞得太复杂，可以这样开始：</p> </p> 先写一些规则和提示词</li> 用简单的搜索工具找文档</li> 写个脚本查 StackOverflow</li> 用 grep</code>、lint</code> 这些工具收集反馈</li> </ol> 这样就有个基础版本了，后面再慢慢改进。</p> 写在最后</a> </h2> Coding Agent 确实在改变编程的方式。它把"查资料"和"写代码"结合起来，让编程助手真正能帮上忙——理解你的需求、找到相关文件、写出能用的代码、帮你调试问题。</p> 不管你是新手还是老手，这些效率工具总归能让工作轻松一些。如果你想自己搞一个，建议从简单的开始，慢慢试验。反正现在这个领域变化很快，说不定你就能做出下一个爆款工具。</p> 总之，这个方向还是很有意思的，值得关注。</p> RAG 没有捷径 2025-04-17T00:00:00+00:00 去年我从数据库基础设施跳进 RAG 项目时，以为终于能摆脱底层细节，结果是另一种更复杂的基础设施扑面而来。RAG 看似应用层，其实处处是工程化的坑。</p> 检索：不只是“找到”</a> </h2> 传统搜索里，我们调索引、调排序，指标相对稳定。RAG 的检索要面对的是语义空间——向量近邻、模型偏差、上下文漂移。今天 QA 能命中“三季度发货策略”，明天可能因为语境不同完全跑偏。检索的目标从“找到哪条记录”变成“理解用户真正想说什么，并确保返回的语段能支撑后续推理”。</p> Agent：别被名字骗了</a> </h2> 大家给 Agent 起了很多酷炫的名字：规划代理、推理代理、工具代理……但它们大多还是条件语句堆出来的工作流。区别只是条件不是硬编码，而是 LLM 动态生成。重点不在“更智能”，而在“如何把工具、状态、反馈闭环结构化”。我们需要的是一个可观察、可替换的流程引擎，模型只是其中的决策组件。</p> Grounding Truth：最后的锚点</a> </h2> 没有扎实的事实校验，RAG 系统只是会讲好听故事的随机鹦鹉。Grounding 不是选配，而是价值锚定。你得持续补充可验证的知识底座，让领域专家参与反馈循环，设计清晰的“证据链”输出格式。否则，Agent 再聪明也只是在幻觉上做推理。</p> 复杂性从哪里来</a> </h2> 数据形态多样</strong>：PDF、截图、音视频、传感器数据同时存在，且要保持语义一致。</li> 一致性概念模糊</strong>：知识会被实时更新，旧答案随时过期。你需要定义“足够新”“足够可信”的标准。</li> 成本与体验拉扯</strong>：检索准确度、上下文长度、延迟、推理深度，一环牵动一环。</li> </ul> 这比建一个数据库、一个 API 难多了，但也更有意思。</p> 为什么还要干</a> </h2> 因为我们在重新定义“信息系统”：</p> 让系统理解人的意图，而不是死背关键词；</li> 让工具链能自我学习、自动拼装；</li> 把抽象的语言推理和现实世界的事实连接起来。</li> </ul> 这是一种新的基础设施：检索、智能体与真实感三元同构。谁能把这三者编排好，谁就掌握下一代知识系统的主动权。</p> 所以，当别人问我为什么离开数据库领域去做 AI 应用时，我会说：“我没离开基础设施，我只是换了一种方式去构建它。”</p> 现在，请允许我回去调向量量化、训几个不听话的 Agent，并确保文本切分策略不会把事实撕裂。这，就是日常的 RAG 工程。</p> NebulaGraph MCP Server 正式开源！探索 AI+图数据库无限可能 2025-03-11T00:00:00+00:00 一、背景</a> </h2> 过去几周，Model Context Protocol (MCP) 在技术社区中引发了广泛的讨论和关注。借此机会，我参与了几个相关的开源项目，包括为 LlamaIndex 官方仓库贡献了 McpToolSpec 实现</strong>，以及和 Xuanwo、FrostMing 合作开发了一版 Model Context Protocol Server for Apache OpenDAL™</strong>。</p> MCP 是目前唯一一个在生态上具有优势的标准。在这一背景下，我们基于 NebulaGraph 3.x 实现了一个简单的 NebulaGraph MCP Server，作为 NebulaGraph X MCP 生态中的第一个基础组件，供大家探索 AI 与图数据库结合的可能性</strong>，希望能够看到更多在这个模式下的有趣工作。</p> 二、Model Context Protocol (MCP)</a> </h2> MCP 是由 Anthropic 团队推出的一项开放协议，旨在为 AI 系统提供统一的、高效的方式访问多种数据资源。通过采用客户端-服务器架构，MCP 将数据访问标准化，解决了传统 AI 系统在不同数据源之间的碎片化问题。</p> MCP 核心特点</a> </h3> 标准化的通信方式</strong>：通过 MCP，AI 助手能够有效地访问各种数据源，比如本地数据、远程服务和企业工具。</li> 开放性与生态优势</strong>：目前 MCP 社区中已有近 1000 个 MCP Server 实现，覆盖搜索、天气、数据库等多个领域，支持工具的快速接入。</li> 灵活的架构</strong>：通过定义客户端和服务端的交互协议，MCP 为开发者提供了构建可扩展、可复用系统的基础。</li> </ol> 虽然目前在安全性和可靠性上仍有一些挑战，但随着协议规范的完善和成熟开发模式的引入，这些问题将逐步得到解决。</p> 三、NebulaGraph MCP Server 功能</a> </h2> 由于最近一段时间一直围绕 GraphRAG 和 Agentic Workflow 做一些工作，利用大模型和智能体进行图上数据的洞见和挖掘是一个非常重要的议题。为此，我快速开发了 NebulaGraph MCP Server，以支持 NebulaGraph 3.x 作为工具接入 MCP 生态，供语言模型（如 Claude、GPT 等）调用和使用。</p> 目前 NebulaGraph MCP Server 基于 FastMCP 实现，遵循 MCP 的核心规范，旨在提供高效、轻量的图数据库连接服务。</strong> 通过将 NebulaGraph 的功能暴露为标准化的工具接口，该 Server 能够让大模型轻松调用 NebulaGraph 数据，实现简单的图探索任务。</p> 多种传输方式</strong>：支持 stdio 和 SSE 两种传输模式，满足不同开发和部署场景的需求。</li> </ul> </li> 基础图探索能力</strong>：图空间（Graph Space）列出：允许模型查询可用的图空间。</li> 模式（Schema）查询：支持查询指定图空间的模式定义。</li> 查询执行（Query Execution）：支持通过 MCP Server 执行 NebulaGraph 查询。</li> </ul> </li> 内置算子模板</strong>：实现了路径搜索和邻居发现等常用操作的模板，方便语言模型按需调用这些工具，快速获取图数据的初步洞察（Insight）。</li> </ul> </li> </ul> 为了展示它的效果，我基于 LlamaIndex 中的 McpToolSpec 和 ReActAgent 构建了一个简单的示例，下面是对应的截图：</p> </p> 四、结语</a> </h2> NebulaGraph MCP Server</strong> 是对 MCP 生态的一个初步尝试，旨在为语言模型和图数据库的结合提供一个起点。随着协议的逐步成熟和生态的扩展，我们期待它能够在更多真实场景中发挥价值。如果您对这一方向感兴趣，欢迎一起探索、尝试！</p> 把 MCP 工具塞进 LlamaIndex 工作流 2025-02-11T00:00:00+00:00 一、前言</a> </h2> 本文主要介绍了如何将 MCP（Model Context Protocol，模型上下文协议）工具转换为可以直接使用的 LlamaIndex 工具，使 LlamaIndex 用户能像使用 Claude, Cursor 等现代 AI 应用一样无缝集成这些服务。</p> 二、技术背景</a> </h2> 2.1 什么是 MCP 协议？</a> </h3> MCP（模型上下文协议，https://modelcontextprotocol.io）是面向 AI 应用交互的服务构建协议。开发者可通过该协议构建具备数据资源（resources）、功能工具（tools）和提示模板（prompts）的服务端点。例如，我们可以定义获取 IP 详细信息的 fetch_ipinfo 工具：</p> @</span></span></span>mcp</span></span>.</span></span>tool</span></span></span></span>(</span></span>)</span></span> </span>async</span> def</span></span> fetch_ipinfo</span></span></span>(</span></span>ip</span></span>:</span> str</span></span> \|</span> None</span> </span>=</span> None</span></span>,</span> </span>kwargs</span>)</span></span> </span>-></span> IPDetails</span></span></span>:</span></span> </span> """</span>获取指定IP的详细信息 </span></span> </span></span> 参数: </span></span> ip(str or None): 目标 IP 地址，格式如 192.168.1.1 </span></span> kwargs: 传递给 IPInfo 处理器的附加参数 </span></span> </span></span> 返回: </span></span> IPDetails: 包含城市、时区等信息的结构化数据 </span></span> """</span></span> </span> handler</span></span> =</span> ipinfo</span></span>.</span></span>getHandler</span></span></span></span>(</span> </span></span> access_token</span>=</span>os</span>.</span>environ</span></span>.</span></span>get</span></span></span></span>(</span>"</span></span></span>IPINFO_API_TOKEN"</span></span></span>)</span></span>,</span> </span></span> headers</span>=</span>{</span></span>"</span></span></span>user-agent"</span></span></span></span>:</span></span> </span>"</span></span></span>basic-mcp-server"</span></span></span></span>}</span></span>,</span> </span></span> </span>kwargs</span></span>,</span> </span></span> )</span></span> </span> details</span></span> =</span> handler</span></span>.</span></span>getDetails</span></span></span></span>(</span>ip_address</span>=</span>ip</span></span>)</span></span> </span> return</span> IPDetails</span></span></span></span>(</span></span></span>details</span>.</span>all</span></span>)</span></span> </span></code></pre> 2.2 LlamaIndex 框架特征</a> </h3> LlamaIndex（https://github.com/run-llama/llama_index）是构建知识索引系统的核心框架，其核心价值在于将外部信息结构化地接入大语言模型，实现高效的信息检索、智能问答和对话生成。当需要集成动态数据源时，将 MCP 工具转换为 LlamaIndex 工具成为关键技术需求。</p> 在 LlamaIndex 中，NebulaGraph 已经有两种方法实现 GraphRAG：KnowledgeGraphIndex 用来对任何私有数据从零构建知识图谱（基于 LLM 或者其他语言模型），再 4 行代码进行 Graph RAG：</p> graph_store</span></span> =</span> NebulaGraphStore</span></span></span></span>(</span> </span></span> space_name</span>=</span>space_name</span></span>,</span> </span></span> edge_types</span>=</span>edge_types</span></span>,</span> </span></span> rel_prop_names</span>=</span>rel_prop_names</span></span>,</span> </span></span> tags</span>=</span>tags</span></span>,</span> </span></span>)</span></span> </span>storage_context</span></span> =</span> StorageContext</span></span>.</span></span>from_defaults</span></span></span></span>(</span>graph_store</span>=</span>graph_store</span></span>)</span></span> </span>#</span> Build KG </span></span>kg_index</span></span> =</span> KnowledgeGraphIndex</span></span>.</span></span>from_documents</span></span></span></span>(</span> </span></span> documents</span></span>,</span> </span></span> storage_context</span>=</span>storage_context</span></span>,</span> </span></span> max_triplets_per_chunk</span>=</span>10</span>,</span> </span></span> space_name</span>=</span>space_name</span></span>,</span> </span></span> edge_types</span>=</span>edge_types</span></span>,</span> </span></span> rel_prop_names</span>=</span>rel_prop_names</span></span>,</span> </span></span> tags</span>=</span>tags</span></span>,</span> </span></span>)</span></span> </span>kg_query_engine</span></span> =</span> kg_index</span></span>.</span></span>as_query_engine</span></span></span></span>(</span>)</span></span> </span></code></pre> KnowledgeGraphRAGQueryEngine 则可以在任何已经存在的知识图谱上进行 GraphRAG:</p> graph_store</span></span> =</span> NebulaGraphStore</span></span></span></span>(</span> </span></span> space_name</span>=</span>space_name</span></span>,</span> </span></span> edge_types</span>=</span>edge_types</span></span>,</span> </span></span> rel_prop_names</span>=</span>rel_prop_names</span></span>,</span> </span></span> tags</span>=</span>tags</span></span>,</span> </span></span>)</span></span> </span>storage_context</span></span> =</span> StorageContext</span></span>.</span></span>from_defaults</span></span></span></span>(</span>graph_store</span>=</span>graph_store</span></span>)</span></span> </span>graph_rag_query_engine</span></span> =</span> KnowledgeGraphRAGQueryEngine</span></span></span></span>(</span> </span></span> storage_context</span>=</span>storage_context</span></span>,</span> </span></span>)</span></span> </span></code></pre> 三、为什么需要将 MCP 集成至 LlamaIndex</a> </h2> 在实际 AI 应用开发中，集成 MCP 工具主要解决以下需求：</p> 功能复用：利用现有 MCP 生态（项目列表见 https://github.com/AlexMili/Awesome-MCP）快速扩展系统能力</li> 流程统一：建立标准化工具调用范式，简化大模型对外部 API 的调用复杂度</li> 自动化管理：通过自动转换机制实现 MCP 工具到 LlamaIndex FunctionTool 对象的映射，便于 Agent 自动调度</li> </ul> 该集成方案可以有效降低开发成本，同时发挥 LlamaIndex 在上下文管理和对话生成方面的优势。</p> 四、技术实现方案</a> </h2> 实现流程包含三个关键阶段：</p> MCP 服务通信：通过 MCPClient 类建立服务连接，支持工具发现（list_tools）和调用执行（call_tool）</li> 适配器构建：定义 MCPToolAdapter 类，将 MCP 工具元数据转换为 LlamaIndex 的 FunctionTool 对象</li> 智能代理集成：在 LlamaIndex Agent 中加载转换后的工具，实现自动化调用</li> </ul> 五、核心代码解析</a> </h2> 协议转换适配器</a> </h3> from</span></span> llama_index</span>.</span>core</span>.</span>tools</span></span> import</span></span></span></span></span> FunctionTool</span></span> </span>from</span></span> pydantic</span></span> import</span></span></span></span></span> create_model</span>,</span> BaseModel</span></span> </span> </span>class</span></span> MCPToolAdapter</span></span>:</span></span> </span> def</span></span> __init__</span></span></span>(</span></span>self</span>,</span> client</span>)</span></span>:</span></span> </span> self</span>.</span>client</span></span> =</span> client</span></span> </span> </span> async</span> def</span></span> list_tools</span></span></span>(</span></span>self</span>)</span></span>:</span></span> </span> tools</span></span> =</span> await</span> self</span>.</span>client</span></span>.</span></span>list_tools</span></span></span></span>(</span>)</span></span> </span> return</span> [</span> </span></span> FunctionTool</span></span>.</span></span>from_defaults</span></span></span></span>(</span> </span></span></span> fn</span>=</span>self</span></span>.</span></span>_create_tool_fn</span></span></span></span>(</span>tool</span>.</span>name</span></span>)</span></span>,</span> </span></span></span> name</span>=</span>tool</span>.</span>name</span></span>,</span> </span></span></span> description</span>=</span>tool</span>.</span>description</span></span>,</span> </span></span></span> fn_schema</span>=</span>self</span></span>.</span></span>_create_pydantic_model</span></span></span></span>(</span>tool</span>.</span>schema</span></span>)</span></span>,</span> </span></span></span> )</span></span> for</span> tool</span> in</span></span> tools</span></span> </span></span> ]</span></span> </span> </span> def</span></span> _create_pydantic_model</span></span></span>(</span></span>self</span>,</span> json_schema</span>)</span></span>:</span></span> </span> #</span> 实现JSON Schema到Pydantic模型的动态转换 </span></span> ...</span> </span></code></pre> 类型系统映射</a> </h3> JSON_TYPE_MAPPING</span></span> =</span> {</span> </span></span></span> </span>"</span></span></span>string"</span></span></span></span>:</span></span> </span>str</span></span></span>,</span> </span></span> </span>"</span></span></span>number"</span></span></span></span>:</span></span> </span>float</span></span></span>,</span> </span></span> </span>"</span></span></span>integer"</span></span></span></span>:</span></span> </span>int</span></span></span>,</span> </span></span> </span>"</span></span></span>boolean"</span></span></span></span>:</span></span> </span>bool</span></span></span>,</span> </span></span> </span>"</span></span></span>object"</span></span></span></span>:</span></span> </span>dict</span></span></span>,</span> </span></span> </span>"</span></span></span>array"</span></span></span></span>:</span></span> </span>list</span></span> </span></span></span>}</span></span> </span> </span>def</span></span> create_dynamic_model</span></span></span>(</span></span>schema</span>)</span></span>:</span></span> </span> fields</span></span> =</span> {</span>}</span></span> </span> for</span> name</span>,</span> prop</span> in</span></span> schema</span></span></span>[</span></span>"</span></span></span>properties"</span></span></span></span>]</span></span>.</span></span>items</span></span></span></span>(</span>)</span></span></span>:</span></span> </span> py_type</span></span> =</span> JSON_TYPE_MAPPING</span></span></span>[</span></span>prop</span></span></span>[</span></span>"</span></span></span>type"</span></span></span></span>]</span></span></span>]</span></span> </span> if</span> name</span></span> in</span> schema</span></span>.</span></span>get</span></span></span></span>(</span>"</span></span></span>required"</span></span></span>,</span> [</span>]</span></span>)</span></span>:</span></span> </span> fields</span></span></span>[</span></span>name</span></span></span>]</span></span> =</span> (</span>py_type</span></span>,</span> Field</span></span></span></span>(</span>...</span>)</span></span>)</span></span> </span> else</span>:</span></span> </span> fields</span></span></span>[</span></span>name</span></span></span>]</span></span> =</span> (</span>Optional</span></span></span>[</span></span>py_type</span></span></span>]</span></span>,</span> Field</span></span></span></span>(</span>None</span>)</span></span>)</span></span> </span> return</span> create_model</span></span></span></span>(</span>"</span></span></span>DynamicModel"</span></span></span>,</span> </span>fields</span></span>)</span></span> </span></code></pre> 服务调用封装</a> </h3> async</span> def</span></span> fetch_ipinfo_wrapper</span></span></span>(</span></span></span>kwargs</span>)</span></span>:</span></span> </span> return</span> await</span> mcp_client</span></span>.</span></span>call_tool</span></span></span></span>(</span>"</span></span></span>fetch_ipinfo"</span></span></span>,</span> kwargs</span></span>)</span></span> </span></code></pre> 关键技术创新点</a> </h3> 动态模式转换：实现 JSON Schema 到 Pydantic 模型的运行时转换，保证参数校验的严格性</li> 异步调用管道：基于 Python asyncio 构建非阻塞式服务调用，提升工具执行效率</li> 协议抽象层：通过适配器模式解耦 MCP 协议与 LlamaIndex 框架，保证系统扩展性</li> </ul> 将 MCP 工具的输入参数转换为 Pydantic 模型的原因在于：MCP 工具使用 JSON Schema 格式定义输入参数（在工具对象的 inputSchema 中，类型为 Dict[str, Any] ），而 create_model_from_json_schema 函数将其转换为 Pydantic 模型，该模型用作 LlamaIndex 中 FunctionTool 的 fn_schema。</p> 六、LlamaIndex 中的 MCP 工具调用实践</a> </h2> 以下代码来自 llamaindex_mcp_example.py，完整展示了 MCPToolAdapter 与 LlamaIndex 的集成方式：</p> import</span> os</span></span></span> </span>from</span></span> llama_index</span>.</span>core</span>.</span>llms</span></span> import</span></span></span></span></span> ChatMessage</span></span> </span>from</span></span> llama_index</span>.</span>core</span>.</span>agent</span></span> import</span></span></span></span></span> ReActAgent</span>,</span> ReActChatFormatter</span></span> </span>from</span></span> llama_index</span>.</span>core</span>.</span>agent</span>.</span>react</span>.</span>prompts</span></span> import</span></span></span></span></span> REACT_CHAT_SYSTEM_HEADER</span></span> </span>from</span></span> llama_index</span>.</span>llms</span>.</span>azure_openai</span></span> import</span></span></span></span></span> AzureOpenAI</span></span> </span> </span>from</span></span> llamaindex_mcp_adapter</span></span> import</span></span></span></span></span> MCPToolAdapter</span></span> </span>from</span></span> mcp_client</span></span> import</span></span></span></span></span> MCPClient</span></span> </span>import</span> anyio</span></span></span> </span>import</span> dotenv</span></span></span> </span>import</span> argparse</span></span></span> </span> </span>dotenv</span></span>.</span></span>load_dotenv</span></span></span></span>(</span>)</span></span> </span> </span>#</span> 系统级指令模板 </span></span>SYSTEM_PROMPT</span></span> =</span> """</span></span></span></span></span></span>\</span> </span></span></span>您是一个智能法律助手 </span></span></span> </span></span></span>在回答用户问题前，必须通过IP信息确认用户所在司法管辖区 </span></span></span>操作规则： </span></span></span>- 当涉及地理位置、时区等问题时，自动调用fetch_ipinfo工具 </span></span></span>- 法律咨询类问题需结合IP所在国家/地区法律体系 </span></span></span>"""</span></span></span> </span> </span>async</span> def</span></span> get_agent</span></span></span>(</span></span>adapter</span></span>:</span> MCPToolAdapter</span></span></span>)</span></span>:</span></span> </span> """</span>智能代理初始化函数"""</span></span> </span> tools</span></span> =</span> await</span> adapter</span></span>.</span></span>list_tools</span></span></span></span>(</span>)</span></span> #</span> 获取MCP工具列表 </span></span> </span> #</span> 配置Azure OpenAI大语言模型 </span></span> llm</span></span> =</span> AzureOpenAI</span></span></span></span>(</span> </span></span> model</span>=</span>os</span>.</span>environ</span></span>.</span></span>get</span></span></span></span>(</span>"</span></span></span>AZURE_OPENAI_MODEL"</span></span></span>,</span> "</span></span></span>gpt-4"</span></span></span>)</span></span>,</span> </span></span> max_tokens</span>=</span>int</span></span></span></span>(</span>os</span>.</span>environ</span></span>.</span></span>get</span></span></span></span>(</span>"</span></span></span>AZURE_OPENAI_MAX_TOKENS"</span></span></span>,</span> 4096</span>)</span></span>)</span></span>,</span> </span></span> azure_endpoint</span>=</span>os</span>.</span>environ</span></span>.</span></span>get</span></span></span></span>(</span>"</span></span></span>AZURE_OPENAI_ENDPOINT"</span></span></span>)</span></span>,</span> </span></span> api_key</span>=</span>os</span>.</span>environ</span></span>.</span></span>get</span></span></span></span>(</span>"</span></span></span>AZURE_OPENAI_API_KEY"</span></span></span>)</span></span>,</span> </span></span> api_version</span>=</span>os</span>.</span>environ</span></span>.</span></span>get</span></span></span></span>(</span>"</span></span></span>AZURE_OPENAI_API_VERSION"</span></span></span>)</span></span>,</span> </span></span> engine</span>=</span>os</span>.</span>environ</span></span>.</span></span>get</span></span></span></span>(</span>"</span></span></span>AZURE_OPENAI_ENGINE"</span></span></span>)</span></span> </span></span> )</span></span> </span> </span> #</span> 构建ReAct智能代理 </span></span> agent</span></span> =</span> ReActAgent</span></span>.</span></span>from_tools</span></span></span></span>(</span> </span></span> llm</span>=</span>llm</span></span>,</span> </span></span> tools</span>=</span>list</span></span></span></span>(</span>tools</span></span>)</span></span>,</span> </span></span> react_chat_formatter</span>=</span>ReActChatFormatter</span></span></span></span>(</span> </span></span></span> system_header</span>=</span>SYSTEM_PROMPT</span></span> +</span> "</span></span></span>\n</span>"</span></span></span> +</span> REACT_CHAT_SYSTEM_HEADER</span></span>,</span> </span></span></span> )</span></span>,</span> </span></span> max_iterations</span>=</span>20</span>,</span> #</span> 限制最大推理步数 </span></span></span> verbose</span>=</span>True</span> #</span> 启用详细日志 </span></span></span> )</span></span> </span> return</span> agent</span></span> </span> </span>async</span> def</span></span> handle_user_message</span></span></span>(</span></span>message_content</span></span>:</span> str</span></span></span>,</span> agent</span></span>:</span> ReActAgent</span></span></span>)</span></span>:</span></span> </span> """</span>消息处理流水线"""</span></span> </span> user_message</span></span> =</span> ChatMessage</span></span>.</span></span>from_str</span></span></span></span>(</span>role</span>=</span>"</span></span></span>user"</span></span></span>,</span> content</span>=</span>message_content</span></span>)</span></span> </span> response</span></span> =</span> await</span> agent</span></span>.</span></span>achat</span></span></span></span>(</span>message</span>=</span>user_message</span>.</span>content</span></span>)</span></span> </span> print</span></span></span></span>(</span>f</span>"</span></span></span>[智能代理响应] </span>{</span>response</span>.</span>response</span></span></span></span>}</span></span>"</span></span></span>)</span></span> </span> </span>if</span> __name__</span></span> ==</span> "</span></span></span>__main__"</span></span></span>:</span></span> </span> async</span> def</span></span> main</span></span></span>(</span></span>)</span></span>:</span></span> </span> #</span> 命令行参数解析 </span></span> parser</span></span> =</span> argparse</span></span>.</span></span>ArgumentParser</span></span></span></span>(</span>)</span></span> </span> parser</span></span>.</span></span>add_argument</span></span></span></span>(</span>"</span></span></span>--client_type"</span></span></span>,</span> </span></span> choices</span>=</span>[</span>"</span></span></span>sse"</span></span></span>,</span> "</span></span></span>stdio"</span></span></span>]</span></span>,</span> </span></span> default</span>=</span>"</span></span></span>stdio"</span></span></span>,</span> </span></span> help</span>=</span>"</span></span></span>连接模式：sse(Server-Sent Events)或stdio(标准输入输出)"</span></span></span>)</span></span> </span> args</span></span> =</span> parser</span></span>.</span></span>parse_args</span></span></span></span>(</span>)</span></span> </span> </span> #</span> MCP客户端初始化 </span></span> if</span> args</span>.</span>client_type</span></span> ==</span> "</span></span></span>sse"</span></span></span>:</span></span> </span> client</span></span> =</span> MCPClient</span></span></span></span>(</span>"</span></span></span>http://0.0.0.0:8000/sse"</span></span></span>)</span></span> #</span> SSE长连接模式 </span></span> else</span>:</span></span> </span> client</span></span> =</span> MCPClient</span></span></span></span>(</span> #</span> 子进程模式 </span></span></span> "</span></span></span>./venv/bin/python"</span></span></span>,</span> </span></span> [</span>"</span></span></span>mcp_server.py"</span></span></span>,</span> "</span></span></span>--server_type"</span></span></span>,</span> "</span></span></span>stdio"</span></span></span>]</span></span> </span></span> )</span></span> </span> </span> #</span> 工具适配器初始化 </span></span> adapter</span></span> =</span> MCPToolAdapter</span></span></span></span>(</span>client</span></span>)</span></span> </span> agent</span></span> =</span> await</span> get_agent</span></span></span></span>(</span>adapter</span></span>)</span></span> </span> </span> #</span> 执行测试用例 </span></span> await</span> handle_user_message</span></span></span></span>(</span>"</span></span></span>我的IP所在城市是哪里？"</span></span></span>,</span> agent</span></span>)</span></span> </span> await</span> handle_user_message</span></span></span></span>(</span>"</span></span></span>持有大麻在我国是否合法？"</span></span></span>,</span> agent</span></span>)</span></span> </span> </span> anyio</span></span>.</span></span>run</span></span></span></span>(</span>main</span></span>)</span></span> #</span> 启动异步运行时 </span></span></code></pre> 关键实现解析</a> </h3> 工具获取机制：通过 adapter.list_tools() 动态加载 MCP 服务端注册的工具列表</li> 自动将每个 MCP 工具转换为 LlamaIndex 的 FunctionTool 对象</li> </ul> </li> 智能代理配置：使用 Azure OpenAI 作为底层大语言模型引擎</li> 集成 ReAct 推理框架，支持多步工具调用</li> 设置 20 步的最大推理深度防止无限循环</li> </ul> </li> 消息处理流程：将用户输入封装为标准化 ChatMessage</li> 通过 agent.achat() 触发自动化工具调用链</li> </ul> </li> </ul> 七、运行 Demo</a> </h2> 7.1 标准输入输出模式</a> </h3> python</span></span> llamaindex_mcp_example.py --</span>client_type</span> stdio</span> </span></code></pre> 执行输出示例</a> </h3> [DEBUG] 检测到ListToolsRequest协议请求 </span>[工具调用] 步骤ID: ede14770-91c9-428b... \| 输入: 我的IP所在城市是哪里？ </span>[推理日志] 当前用户语言：中文，需调用工具获取数据 </span>[动作触发] fetch_ipinfo \| 参数: {} </span>[网络请求] 调用MCP工具耗时128ms </span>[观察结果] {"ip": "183.193.123.192", "city": "上海", "country": "CN"...} </span>[最终响应] 您的IP所在城市为上海 </span> </span>[法律咨询] 步骤ID: e728f5d0-6c0e-454a... \| 输入: 持有大麻是否合法？ </span>[推理日志] 已确认用户所在国家：中国 </span>[知识库检索] 加载中国刑法第357条 </span>[最终响应] 根据中国法律，持有大麻属违法行为，最高可判处有期徒刑 </span></code></pre> 7.2 SSE 服务模式</a> </h3> #</span></span> 终端1：启动SSE服务端</span> </span></span>python</span></span> mcp_server.py --</span>server_type</span> sse</span> </span> </span>#</span></span> 终端2：运行客户端</span> </span></span>python</span></span> llamaindex_mcp_example.py --</span>client_type</span> sse</span> </span></code></pre> 八、技术方案总结</a> </h2> 通过以下三步实现深度集成：</p> 协议通信层</a> </h3> 基于 MCPClient 实现服务发现与工具调用</li> 支持 SSE/STDIO 双模连接，适应不同部署场景</li> </ul> 类型转换层</a> </h3> 动态将 JSON Schema 转换为 Pydantic 模型</li> 实现参数自动校验与类型提示</li> </ul> def</span></span> create_dynamic_model</span></span></span>(</span></span>schema</span>)</span></span>:</span></span> </span> #</span> 自动生成带字段描述的Pydantic模型 </span></span> fields</span></span> =</span> {</span> </span></span></span> </span>name</span></span></span>:</span></span> </span>(</span>map_type</span></span></span></span>(</span>prop</span></span>)</span></span>,</span> Field</span></span></span></span>(</span>...</span>,</span> description</span>=</span>prop</span></span></span>[</span></span>"</span></span></span>description"</span></span></span></span>]</span></span>)</span></span>)</span></span> </span></span></span> for</span> name</span>,</span> prop</span> in</span></span> schema</span></span></span>[</span></span>"</span></span></span>properties"</span></span></span></span>]</span></span>.</span></span>items</span></span></span></span>(</span>)</span></span> </span></span> }</span></span> </span> return</span> create_model</span></span></span></span>(</span>"</span></span></span>DynamicModel"</span></span></span>,</span> </span>fields</span></span>)</span></span> </span></code></pre> 智能代理层</a> </h3> 集成 ReAct 推理框架实现自动化工具调度</li> 通过系统提示词约束工具使用规范</li> </ul> SYSTEM_PROMPT</span></span> =</span> """</span></span></span></span></span></span>\</span> </span></span></span>法律咨询必须遵循以下规则： </span></span></span>1. 首次响应前必须调用fetch_ipinfo确认用户辖区 </span></span></span>2. 引用法律条文需标注具体条款编号 </span></span></span>3. 不得对未覆盖地区提供法律建议"""</span></span></span> </span></code></pre> 通过持续扩展 MCP 生态，开发者可快速构建具备专业领域能力的智能代理系统。欢迎访问 MCP 开发者社区获取更多工具资源。</p> 查看源代码：https://github.com/psiace/psiac</p> VLM 解析非结构化图像：一个极简可扩展方案 2024-11-28T00:00:00+00:00 这篇文章展示一种非常直接的做法：用 VLM（Visual Language Models）解析图片中的非结构化信息。</p> 它足够简单，但也保留了明确的扩展路径，比如继续支持 PDF、表格、视频帧等更复杂场景。</p> 如果你想要一条更重型的工业化路线，可以看 LlamaParse</a> 这类产品，它会叠加 OCR、表格解析等更多步骤。</p> 我们先看一个常见场景：你有一批图片，需要抽取文字；或者你想给图片生成可检索描述，用于全文搜索。</p> 这类事情，正适合交给 VLM。</p> 我示例里用的是 llama_index</a>，但核心思路和具体框架无关，迁移到你自己的客户端也很容易。</p> 先上代码</a> </h2> 第一步是定义一个明确的提示词，让模型知道输出结构和覆盖范围。</p> BASIC_PROMPT</span></span> =</span> """</span></span></span> </span></span></span> </span></span></span>Please analyze this image comprehensively and provide the following information: </span></span></span> </span></span></span> 1. General Overview: </span></span></span> - Main subject matter and content </span></span></span> - Overall composition and context </span></span></span> - Key visual elements present </span></span></span> </span></span></span> 2. Text Content: </span></span></span> - Transcribe any visible text accurately </span></span></span> - Include headers, labels, and captions </span></span></span> - Note any important text formatting or emphasis </span></span></span> </span></span></span> 3. Data Visualization (if present): </span></span></span> - For tables: </span></span></span> Convert to markdown format </span></span></span> * Preserve column headers and data relationships </span></span></span> - For charts/graphs: </span></span></span> * Describe the type of visualization </span></span></span> * Explain key trends and patterns </span></span></span> * List important data points and values </span></span></span> - For diagrams/flowcharts: </span></span></span> * Explain the structure and relationships </span></span></span> * Describe the flow or process </span></span></span> * Note any important symbols or annotations </span></span></span> </span></span></span> 4. Additional Details: </span></span></span> - Identify any branding or logos </span></span></span> - Note color schemes if significant </span></span></span> - Describe any relevant metadata or context </span></span></span> </span></span></span> Please format the response clearly and maintain the original structure of any data. </span></span></span> """</span></span></span> </span></code></pre> 接下来是一个最小可运行的图片解析器：</p> from</span></span> pathlib</span></span> import</span></span></span></span></span> Path</span></span> </span>from</span></span> typing</span></span> import</span></span></span></span></span> List</span></span> </span>import</span> base64</span></span></span> </span>from</span></span> io</span></span> import</span></span></span></span></span> BytesIO</span></span> </span>from</span></span> PIL</span></span> import</span></span></span></span></span> Image</span></span> </span>from</span></span> llama_index</span>.</span>core</span>.</span>multi_modal_llms</span></span> import</span></span></span></span></span> MultiModalLLM</span></span> </span>from</span></span> llama_index</span>.</span>core</span>.</span>multi_modal_llms</span>.</span>generic_utils</span></span> import</span></span></span></span></span> ImageDocument</span></span> </span> </span> </span>class</span></span> SimpleImageParser</span></span>:</span></span> </span> def</span></span> __init__</span></span></span>(</span></span>self</span>,</span> model</span></span>:</span> MultiModalLLM</span></span></span>)</span></span>:</span></span> </span> self</span>.</span>model</span></span> =</span> model</span></span> </span> self</span>.</span>prompt</span></span> =</span> BASIC_PROMPT</span></span> </span> </span> """</span>A simple parser for extracting information from images using VLMs. </span></span> </span></span> Args: </span></span> model (MultiModalLLM): The multi-modal language model to use for parsing </span></span> """</span></span> </span> </span> def</span></span> process_image</span></span></span>(</span></span>self</span>,</span> image_path</span></span>:</span> str</span></span></span>)</span></span> </span>-></span> str</span></span></span>:</span></span> </span> """</span>Convert image to base64 encoding"""</span></span> </span> image</span></span> =</span> Image</span></span>.</span></span>open</span></span></span></span>(</span>image_path</span></span>)</span></span> </span> buffered</span></span> =</span> BytesIO</span></span></span></span>(</span>)</span></span> </span> image</span></span>.</span></span>save</span></span></span></span>(</span>buffered</span></span>,</span> format</span>=</span>"</span></span></span>PNG"</span></span></span>)</span></span> </span> return</span> base64</span></span>.</span></span>b64encode</span></span></span></span>(</span>buffered</span></span>.</span></span>getvalue</span></span></span></span>(</span>)</span></span>)</span></span>.</span></span>decode</span></span></span></span>(</span>"</span></span></span>utf-8"</span></span></span>)</span></span> </span> </span> async</span> def</span></span> parse</span></span></span>(</span></span>self</span>,</span> image_path</span></span>:</span> str</span></span></span>)</span></span> </span>-></span> str</span></span></span>:</span></span> </span> """</span>Parse image content"""</span></span> </span> image_data</span></span> =</span> self</span></span>.</span></span>process_image</span></span></span></span>(</span>image_path</span></span>)</span></span> </span> image_doc</span></span> =</span> ImageDocument</span></span></span></span>(</span> </span></span> image_url</span>=</span>f</span>"</span></span></span>data:image/jpeg;base64,</span>{</span>image_data</span></span></span></span>}</span></span>"</span></span></span> </span></span> )</span></span> </span> response</span></span> =</span> await</span> self</span>.</span>model</span></span>.</span></span>acomplete</span></span></span></span>(</span> </span></span> prompt</span>=</span>self</span>.</span>prompt</span></span>,</span> </span></span> image_documents</span>=</span>[</span>image_doc</span></span>]</span></span> </span></span> )</span></span> </span> return</span> str</span></span></span></span>(</span>response</span></span>)</span></span> </span></code></pre> 核心只有两步：</p> 把图片转成 base64。</li> 作为 image_documents</code> 传给 VLM。</li> </ol> 跑一圈</a> </h2> 下面是如何使用这个解析器：</p> import</span> asyncio</span></span></span> </span>import</span> os</span></span></span> </span>import</span> argparse</span></span></span> </span>from</span></span> pathlib</span></span> import</span></span></span></span></span> Path</span></span> </span>from</span></span> llama_index</span>.</span>multi_modal_llms</span>.</span>openai</span></span> import</span></span></span></span></span> OpenAIMultiModal</span></span> </span>from</span></span> dotenv</span></span> import</span></span></span></span></span> load_dotenv</span></span> </span> </span>load_dotenv</span></span></span></span>(</span>)</span></span> </span> </span> </span>async</span> def</span></span> main</span></span></span>(</span></span>)</span></span>:</span></span> </span> parser</span></span> =</span> argparse</span></span>.</span></span>ArgumentParser</span></span></span></span>(</span>description</span>=</span>"</span></span></span>Parse image content"</span></span></span>)</span></span> </span> parser</span></span>.</span></span>add_argument</span></span></span></span>(</span>"</span></span></span>image_path"</span></span></span>,</span> type</span>=</span>str</span></span>,</span> help</span>=</span>"</span></span></span>Path to the image file"</span></span></span>)</span></span> </span> args</span></span> =</span> parser</span></span>.</span></span>parse_args</span></span></span></span>(</span>)</span></span> </span> </span> image_path</span></span> =</span> Path</span></span></span></span>(</span>args</span>.</span>image_path</span></span>)</span></span> </span> if</span> not</span> image_path</span></span>.</span></span>exists</span></span></span></span>(</span>)</span></span>:</span></span> </span> print</span></span></span></span>(</span>f</span>"</span></span></span>Image file does not exist: </span>{</span>image_path</span></span></span></span>}</span></span>"</span></span></span>)</span></span> </span> return</span> </span> </span> #</span> Initialize the VLM </span></span> model</span></span> =</span> OpenAIMultiModal</span></span></span></span>(</span> </span></span> model</span>=</span>os</span></span>.</span></span>getenv</span></span></span></span>(</span>"</span></span></span>MULTI_MODAL_LLM_MODEL"</span></span></span>,</span> "</span></span></span>gpt-4o-mini"</span></span></span>)</span></span>,</span> </span></span> api_key</span>=</span>os</span></span>.</span></span>getenv</span></span></span></span>(</span>"</span></span></span>MULTI_MODAL_LLM_API_KEY"</span></span></span>)</span></span>,</span> </span></span> api_base</span>=</span>os</span></span>.</span></span>getenv</span></span></span></span>(</span>"</span></span></span>MULTI_MODAL_LLM_API_BASE"</span></span></span>,</span> "</span></span></span>https://api.openai.com/v1"</span></span></span>)</span></span>,</span> </span></span> max_new_tokens</span>=</span>int</span></span></span></span>(</span>os</span></span>.</span></span>getenv</span></span></span></span>(</span>"</span></span></span>MULTI_MODAL_LLM_MAX_TOKENS"</span></span></span>,</span> "</span></span></span>512"</span></span></span>)</span></span>)</span></span>,</span> </span></span> temperature</span>=</span>float</span></span></span></span>(</span>os</span></span>.</span></span>getenv</span></span></span></span>(</span>"</span></span></span>MULTI_MODAL_LLM_TEMPERATURE"</span></span></span>,</span> "</span></span></span>0.7"</span></span></span>)</span></span>)</span></span>,</span> </span></span> verbose</span>=</span>os</span></span>.</span></span>getenv</span></span></span></span>(</span>"</span></span></span>MULTI_MODAL_LLM_VERBOSE"</span></span></span>,</span> "</span></span></span>False"</span></span></span>)</span></span>.</span></span>lower</span></span></span></span>(</span>)</span></span> ==</span> "</span></span></span>true"</span></span></span>,</span> </span></span> )</span></span> </span> </span> #</span> Create parser and parse image </span></span> parser</span></span> =</span> SimpleImageParser</span></span></span></span>(</span>model</span></span>)</span></span> </span> result</span></span> =</span> await</span> parser</span></span>.</span></span>parse</span></span></span></span>(</span>str</span></span></span></span>(</span>image_path</span></span>)</span></span>)</span></span> </span> print</span></span></span></span>(</span>result</span></span>)</span></span> </span> </span> </span>if</span> __name__</span></span> ==</span> "</span></span></span>__main__"</span></span></span>:</span></span> </span> asyncio</span></span>.</span></span>run</span></span></span></span>(</span>main</span></span></span></span>(</span>)</span></span>)</span></span> </span></code></pre> 这段代码会初始化 VLM，创建解析器，然后输出解析结果。</p> 运行 Demo</a> </h2> 完整示例代码在这里：</p> psiace/demo/vlm-parsing</a></li> </ul> 运行方式：</p> python</span></span> basic.py <</span>image_path></span> </span></span></code></pre> 示例图片是一张家庭网关界面截图（来源：Home gateway example</a>）：</p> </p> 终端中的解析输出示例：</p> </p> Bonus：如何扩展这个 Parser</a> </h2> 下面是几个实用扩展方向：</p> 格式支持</strong></li> </ol> 用 pdf2image</code> 处理 PDF。</li> 用 opencv-python</code> 抽取视频帧后再解析。</li> </ul> 输出形态</strong></li> </ol> 增加 JSON 输出：</li> </ul> async</span> def</span></span> parse_to_json</span></span></span>(</span></span>self</span>,</span> image_path</span></span>:</span> str</span></span></span>)</span></span> </span>-></span> dict</span></span></span>:</span></span> </span> result</span></span> =</span> await</span> self</span></span>.</span></span>parse</span></span></span></span>(</span>image_path</span></span>)</span></span> </span> #</span> Add your JSON transformation logic here </span></span> return</span> json_result</span></span> </span></code></pre> 用 Jinja2 等模板工具生成更稳定的结构化文本。</li> </ul> 处理流水线</strong></li> </ol> 接入 Tesseract OCR 做文字前处理。</li> 追加表格解析能力。</li> 用 asyncio 做批处理。</li> </ul> 系统集成</strong></li> </ol> 接入 llama-index 做 RAG。</li> 进一步封装成自动化工作流。</li> </ul> Resources</a> </h2> llama-index Documentation</a></li> OpenAI</a></li> PIL (Python Imaging Library)</a></li> </ul> 如果你只想快速验证“VLM 解析图片”是否有业务价值，这个极简方案足够开始。</p> 先跑通最小闭环，再决定是否引入 OCR、表格结构化和更复杂的工程管线。</p> 别急着招 DevRel 2024-03-08T00:00:00+00:00 先别打广告牌</a> </h2> 很多团队把 DevRel 想成会写文案、会上台、能在社交媒体刷存在感的“吉祥物”。真要这样，不如直接买块广告牌，或者训练一只会说话的鹦鹉。DevRel 如果只是扩音器，迟早会在会议室里被当成背景音。</p> 真正的 DevRel 是把产品和开发者社区连接起来的桥。从用户视角出发，帮团队把复杂的技术语言翻译成可理解、可落地的解决方案。他既要懂产品路线，也要摸得清社区脉搏；既能撸代码，也能写故事。</p> 三件事想清楚</a> </h2> 1. 权责资源要匹配</a> </h3> DevRel 需要参与决策，至少要能影响产品优先级和内容走向。如果每次都被挡在“等业务拍板”之外，他说的任何话都会显得苍白。给予授权，也意味着给足资源：真实数据、工程背景、核心成员的时间。</p> 2. 叙事要一致</a> </h3> 让 DevRel 深入团队，把一线的设计取舍、踩坑记录都吸纳进来。只有这样，他们写出来的内容才像亲历者——不是新闻稿，也不是照本宣科的教程，而是能回答“为什么值得一试”这样的疑问。</p> 3. 诚恳比形式更难</a> </h3> 社区对虚假的热情特别敏感。与其用堆砌的 buzzword，不如老老实实讲“我们是怎么解决 X 问题的”“我们做错过什么”。真诚是唯一的复利策略。</p> 什么时候暂缓</a> </h2> 如果你还没准备好让 DevRel 拿到这些权力与资源，那就别急着招人。让创始人或者资深工程师先上阵：他们说话更有分量，也更容易获得团队信任。真正需要 DevRel 的时刻，是你想把这套叙事机制变成常态的时候。</p> DevRel 永远不是灵丹妙药。它是一种长期投入，需要团队，把“讲清楚”和“做得好”同时放在心上。</p> A New Beginning, with Astro 2023-09-25T00:00:00+00:00 中文翻译正在整理，以下为英文原文。</em></p> </blockquote> Hey, World!</a> </h2> I am delighted to announce the launch of my new blog, which is powered by Astro</a> and features the Astro Cactus</a> theme.</p> In this fresh start, I have cleared all previous content to create a clean slate.</p> Why and Why Not?</a> </h2> The idea of starting anew had been on my mind for a few months, but it was my recent conversation with @Xuanwo</a> that finally pushed me to take action.</p> There are numerous reasons behind this decision:</p> I aspire to connect with a broader audience and have a more significant impact.</p> </blockquote> I aim to express my insights more effectively, moving beyond mere documentation of events.</p> </blockquote> However, in reality, the decision was not driven by extensive contemplation; it was simply a matter of “Why not?”</p> Striving to do my best is sufficient.</p> I hope you’ll join me on this exciting journey!</p>

尚卓燃 · PsiACE - 文章

木匠，锤子，钉子

2026-02-27T00:00:00+00:00

这篇文章继续献给 bub ，一个在群聊中生活的 agent ，来讲讲背后的问题、范式和模型变迁。 kemingy</a> 吐嘈过：“你的文章疑似太发散了，脱离了科技写作的范畴，需要额外的 context，也不一定能对得上”。好在本次是要在公司内部做一个分享开始撰写的，所以难得正经地会走一下流程。 </blockquote>
前言 </a> </h2>
GitHub</a> 。
即便只是在 coding agent 这个子领域上，我至少做过 rag、沙箱、agent、protocol 几个方向，其中 agent-client-protocol</a> 在整个 python 生态下载量大概前万名（1.2%），而这些都不曾是我的主业。
今天分享主要是我过去几年做 Agent 和最近重新拾起 bub</a> 的一些想法和经验的投影。bub 在短短的几天内从一个简单的 Coding Agent 开始，独立地演化成某种类似 OpenClaw 但不同的形态。
最近的视角会更多偏产品经理一些，所以这次不会涉及特别深入的技术点。在进入正题前，先让我们看看这个标题，《木匠，锤子，钉子》：

一个人有了锤子，就会看什么都像钉子。</li>
但如果一个有锤子的人能够分辨哪些东西是钉子，就成功了。</li>
当我有了锤子的时候，不是钉子的东西就不多了。</li> </ul>
也欢迎大家阅读我的历史文章。
如何得到一个 Coding Agent
欢迎阅读 - Baby Steps: 用 Python 实现一个能自举的 Coding Agent</a>
聊聊 RAG 及其适用性
欢迎阅读：当 RAG 遇上编程助手</a>
OpenClaw 和 Bub 背后的不同范式

树立身份认知</li>
欢迎阅读 - 即时通讯与社会化评估</a>
会话、记忆与上下文
欢迎阅读 - 被缚的普罗米修斯</a>。
用纸带和锚点重新建立问题模型
欢迎阅读 - 重新发明打孔纸带</a>
尾声 </a> </h2>
再回到标题上：
特别感谢 frostming</a>，感谢 yihong0618</a>、bub</a> 和其贡献者们。
感谢 alma、kapy、葫芦娃和这些 Agent 背后的创造者。
谢谢大家。

即时通讯与社会化评估

2026-02-21T00:00:00+00:00

这是一篇简单的小短文，主要讨论即时通讯下的人与 Agent 协作，以及为什么更需要社会化评估而不是各种 benchmark。

我们目前在群聊之中培育 bub ，并且观察到它和另一个 agent 小伙伴 kapy 的技能传递过程，有感而发。我们在一个多人群聊中同时与三至四个 Agent 一同协作，任务是并发的、断裂的，随时需要为切换做好准备。有些人可能更关心视频、图片的分析，有些人只想听个睡前故事，有些人因为如何利用 livecd 如何修复 Linux 桌面环境而发愁，中间还要夹杂过年的祝愿和风土人情大盘点。另外，这些 agent 都是从 0 开始写的，而不是某一些已经大获流行的实现。 </blockquote>
即时通讯的“蜜罐”
迈向社会化评估

被缚的普罗米修斯

2026-02-16T00:00:00+00:00

会话，一个具体问题
Memory ，失败的实验品
Context ，另一个糖衣炮弹
更聪明和更少假设
大道至简
推荐阅读 </a> </h2>

创造一只龙虾，需要些什么?</a></li>
重新发明打孔纸带</a></li>
bub</a></li>
AI Programming Is a New Framework</a></li> </ul>

重新发明打孔纸带

2026-01-28T00:00:00+00:00

大家好，我是 PsiACE</a>，你可以在 GitHub 上找到我，这个想法最开始诞生于 4 个月前，那个时候我还在为更好的 GraphRAG 而努力。我过去几年在 Agent 和数据库有一些经验，你也可以阅读我的历史文章。 </blockquote>
TL;DR
无尽的长纸带车轮滚滚向前新的打孔纸带计算机

只是谈谈工作
愿开源庇佑你我
奔向更美好的生活
留一些笔墨给 AI

测试并不等价于覆盖率
测试是在对语义做长期约束
结语

拾遗篇
Databend 篇 Apache OpenDAL 篇</a> </h2> 我和漩涡认识于他处理官网迁移的时候。当时的存储访问层是 dal，应该是老赵设计的，但是我们需要兼顾对象存储和 HDFS。漩涡建议重写成通用接口，于是他做了 dal2，后来独立出来成为 opendal。 菜菜子做了早期 WebHDFS 的集成，Databend 也顺势补了 hive 支持。数据公司大抵都有一些类似的需求，opendal 被不少友商关注，在 tison 的帮助下进入基金会孵化。 在 opendal 前，我只是拿工资写开源。在这里，我体验到不用利润目标也能靠信任合作，“community over code”。 赌城求学</a> </h2> 全职一年后我去澳门读应用数学与数据科学。可能是宅久了，也可能是觉得还不够好，总之想出去看看。 数学课很多，上一节课要掉不少头发，好在最后也一路学过了凸优化。 AI 和大模型这时候也开始进入到我的学习和生活：利用 Meta 的 SAM 做分割，结合 CLIP 做交互式 caption，在 nanogpt 上改模型结构、优化器和学习率调度。 和 Databend 的联系仍然紧密：编译和 Rust 优化，做过几次分享；探索分析 lakeFS、HuggingFace 的数据；做 kubesphere 4.0 集成和 databend playground；办过线上 hackathon；管大部分中文文档，维护大模型转写英文文档的工作流；当时还面临企业版功能的源代码是否应该开放的讨论，我也翘课参加。 23 年 Apache Con 第一次线下见到 Xuanwo，我们各讲一个 OpenDAL 主题。他是第一个给我寄过喜糖的同事，我也偶尔充当他的合并机器人。那次还见到 tison、saka、f 叔、xp，还和 TCeason 一起去了颐和园。后来又有机会见到之晗、Eric；Rust conf 认识 RisingWave 的朋友，很多 ID 和面容有了映射。 24 年去日本玩了一圈后专心毕设，主题是现代缓存替换算法。和 juncheng 聊过一次，他主导了 sieve、s3fifo 等几个非常简洁有趣的算法设计。毕业迫使我收拢精力，那是一段煎熬的时刻，还好我的导师总是以一副宁静的姿态出现。我顺利毕业，也离开了 Databend，最后一次公开分享是《面向现代分层存储的 Caching 技术漫谈》。 NebulaGraph 篇</a> </h2> 离开 Databend 之后要再找工作。我还想做 data infra，也想过投递一些不那么技术的岗位。市场很冷，两家同行业公司一路面到 CXO 也没结果。大厂面试不算投机，面试官对我的经历不太感冒，我也没有过多准备在算法和八股上。朋友介绍了几家 web3，虽然拿到高薪 offer 但还是顾虑合规问题，只能作罢。 转机在杭州 Apache Con。我见到几个 Graph 厂商的朋友，从慧姐和盐粒的口中才知道 NebulaGraph 的 GenAI 团队在招人，leader 是多年的推友 wey-gu。最后一轮是 sherman，除了常规问答，还考了一道口述算法，很难想到这会出现在文化相性的面试上。 入职前我去上海参加 Rust Conf，也顺便认认上海办公室的位置。终于见到 yihong0618，一个非常有趣的灵魂。也第一次见到 RisingWave 的其他朋友，叉鸽（foyer-rs）、润基（arrow-udf），6 个月后在 KCD Beijing，我还去了他们的北京办公室，吃到了美味的小鱼干。 PyCon China 2024 上，wey 做主题分享，我认识了 frostming、晋涛，还和粉头发 saka 合了影。到了 2025 的 Rust Conf 上，有机会见到雷少和 andy ，他们和 tison 一起创业做新产品。再晚一点的 PyCon 我便有了一个讲 coding agent 的主题，和好多群友也是这次相会。 业余收获也多：做了 llama index 社区的第一个 mcp 集成方案，并且贡献了第一版实现到官方 repo；写了第一个 agentclientprotocol Python SDK，在 JetBrains 朋友帮助下成了官方 SDK；还拜访了他们上海办公室，拎了一筐周边回家。 我们从浦东搬到南京西路，从小黑屋搬到阳光间。慧姐离开去了 oceanbase，wey 离职创业做 nowledage memory，我和盐粒继续在 graph rag 和 agent 上折腾，落地了当初想的 Fusion GraphRAG。邵老师负责端到端评估，坚持先把召回率和准确率搞上去。它让 GraphRAG 的上手成本接近向量或全文 RAG，并且在一些领域问答准确率到 95%+。 尾声</a> </h2> 时间走到 2025 年末，好像也就到这里了。
Agent Client Protocol Python SDK 的新篇章 2025-11-07T00:00:00+00:00 当我最初开始编写 Agent Client Protocol Python SDK</a> 时，它只是一个出于好奇的小项目。我想弄清楚 coding agents 是如何交流的——状态、意图与消息在客户端和智能体之间如何流动。 随着时间推移，它逐渐成长为一个真正有用的项目。越来越多的开发者开始使用它，从 Moonshot 到其他探索智能体工作流的公司。 SDK 的架构变得稳定，并持续与 ACP 规范保持同步，成为多种实际集成的基础。 今天，是一个新的开始。 Python SDK 已经正式迁移到 agentclientprotocol</a> 组织下，与 TypeScript、Rust、Kotlin SDK 一起成为官方生态的一部分。 我会继续在新组织下维护和改进它，专注于让它更加可靠、简洁、易于集成，让更多开发者能够轻松构建智能体系统。 特别感谢 Sergey Ignatov、Anna 和 Ben 在整个迁移过程中给予的信任与支持，也感谢所有曾经使用、贡献或反馈过这个项目的开发者们。 这个项目最初只是一个实验，如今它已成为一个共同的努力。愿我们一起迎接新的篇章。 — 尚卓燃（PsiACE） Maintainer, ACP Python SDK Live a Little · 上篇（2016 – 2021） 2025-10-20T00:00:00+00:00 在代码与青春之间 我即将二十七岁。按新时代的算法，已经稳稳进入「老登」序列。这一年，我的第二份正式工作也满了一年多。回头看，想聊聊那些年我和代码之间的故事。 </blockquote> 2016：少年意气与第一行代码</a> </h2> 把时间拨回 2016 年。那时我沉迷小说，读过的大部头早已按「车载斗量」计。 Ruby 风头正盛，我用 Rails 搭过小站，也在 GitHub 上部署过 Jekyll 生成的静态页。想写漂亮 UI 的冲动驱使我去学 HTML；我偷偷读完了 Digital Design and Computer Architecture ——一本讲 Verilog HDL 和计算机体系结构的书。那时我并不真正懂，只是怀着一点少年心气。 2017 – 2018：大学、算法与初恋</a> </h2> 2017 年，我进入大学，主修计算机科学与技术。学校很大，疫情前的校车也只能遍历小半个校区。数学天赋平平，但我仍喜欢编程——因为它让我能「造点什么」。 2018 年，我试图认真地学算法与英语，已经在 Linux 环境下生活。我读 GNU 和自由软件基金会的故事，也在 GNU.org 帮忙校对文章。那时的我还不会 git 之外的工具，全靠前辈帮我合并推送。在邮件列表里，我看到俊余的名字——几年后，他做的 WebP 图像服务在推特上火爆一时。 同年我写信给刚落地中国的 LeetCode 力扣</a>，想参与题解翻译。 Hercy 给我了第一封正式回复。和 Winston 一起帮我做了 landing 。如今一晃也结缘七年。 当然，2018 也有更多故事：我挂了高数，也遇见了现在的女朋友。那年秋天我和工作室的朋友一起看《昨日青空》，出来吃小吃时我说： 「这电影该和女生一起看。」后来我又买了两张票，和学妹二刷—— 转眼，我们已经在一起七年。 </blockquote> 技术上，18 年我第三次重生 GitHub 账号，尝试 Rust 项目 Servo，学 Cargo 命令，修 README 里的构建流程。当时谁能想到，我未来有一段工作会真正用 Rust 写代码。 2019：翻译、社区与早期项目</a> </h2> 翻译比我想的走得更远。 2019 年，LCTT</a> 仍是国内最活跃的 Linux 中文社区。我在里面结识了老王和白宦成老师；我们计划合写一本书，虽最终搁浅，但那段共同写作的日子至今难忘。 技术上，Python 当时如日中天。我学了 Flask、Django、FastAPI 皮毛，用 Cookiecutter 生成项目模板。后来成为 audreyfeldroy/cookiecutter-pypackage</a> 的维护者——一个几千 star 的项目。她和 Pydanny 是有名的「夫妻店」，今天依然活跃。 年底，我修完编译原理课，读 Crafting Interpreters，写了个 C 语言项目的模板 meco</a> 和玩具语言 emo</a>。那时也尝试 Neo4j 与 NebulaGraph，做过可视化图查询的项目。我没想到，几年后我真会在图数据库公司工作。 2020：Rust 之夏与方向初定</a> </h2> 2020 准备考研，但心思其实一半在代码。我从 Python 转向 Rust，入选首届开源之夏 OSPP</a>，在 Casbin 写了 casbin-raft</a>，认识了江成和 Hackerchai。江成后来为我写了推荐信，chai 去了 Kong。和 OSPP 的缘分甚至更深，一直延续到今天。 同年，我在 Rust 中文社区贡献翻译：译过 Writing an OS in Rust 中的一章，与洛佳结识——后来他做了 RustSBI</a>。我还翻译了 nrc 的 “Early Impressions of Go from a Rust Programmer” 。 PingCAP 的 VLDB 论文成为了毕设开题材料。这个内容在获得授权后发布在了 PsiACE/TiDB-A-Raft-based-HTAP-Database</a> 毕业设计题是 “基于 Rust 的分布式 KV”——Raft + Bitcask。熟悉 PingCAP 的同学应该都知道灵感出自何处。我研究 async-raft（即 databend/openraft</a> 前身），也给 P 社周边库提 PR。那年我以个人捐赠者身份支持 Rust China Conf 2020</a>，和夏歌、Mike、汉东有了更多交流。后来，我还做了几年 Rust 中文社区日报编辑。 2021：转折与第一份工作</a> </h2> 考研失败——毕竟我复习间隙还在给 xi-editor</a> 修过 lint。我去 Wasmedge 面试实习，了解到了 WebAssembly 和 ERC20 标准，我修正的方案最后被用于社区。又从 Meilisearch 和 Hashlink 分叉出 riteraft</a> 和 ritelinked</a>，前者积累 300 多 star，后者成为我下载量最高的 crate 之一。 我也拿到 PingCAP 面试机会，当时项目是给 Tichi</a> 做贡献。练习部署 Prow 时，第一次切身感受国内网络之艰难。 Mini256 就在那个组里——几年后，我在做 GraphRAG 时看到 TiDB 推出 AutoFlow，他也在做 RAG 了。 那段时间，我一边写论文，一边给 Databend</a> 做早期贡献，从 CI 到模糊测试，再到上游的 Arrow 和 SQL 解析器。那时 Databend 不过 10 人左右。我加了虎哥好友，只想向技术大佬多学习，没想到真的因此获得了工作机会。他爽快地约我在武汉见面。我至今记得那天的阳光—— 那是创业者最有光的年纪。 6 – 7 月间，我在 Databend 上下游提了约 40 个 PR。就这样，我加入了这个立志打造“中国版 Snowflake”的团队，开始了我的第一份真正意义上的工程师工作。 未完待续 —— Part 2 将讲述 2022 至 2025，从 Databend 到 Apache OpenDAL 等这些年的故事。 </blockquote> 用 Spec 做 SDK - 生成式 AI 的时代 2025-10-15T00:00:00+00:00 AI 写得快，但容易膨胀； Spec 很严格，但可能僵化。 我选择中间那条路—— 让 AI 在边界内跑，让人对结果负责。 </blockquote> 为什么不是全 AI，也不是全 Spec</a> </h2> AI 写代码的速度让人上瘾；一旦规模扩大，很容易出现上下文漂移、结构膨胀、边界模糊——项目“能跑但不稳”。 另一个极端是 spec 驱动：严谨，但往往过重。GitHub 推出的 Spec Kit</a> 倡导“先规范再生成”，对快速迭代的团队并不总是友好，容易过度设计、难以跟踪决策。 我走中间态：在维护 Agent Client Protocol (ACP)</a> 的 Python SDK</a> 时，用规范约束 AI 生成，用 AI 加速规范适配。 ACP：为 SDK 而生的协议</a> </h2> ACP 由 Zed</a> 发起，定义编辑器 ↔ Agent 的通信方式。它采用 JSON-RPC 2.0</a> 作为通信机制，并以 JSON Schema 描述数据结构（典型 schema 见 ACP 仓库）。边界明确、类型可机读、行为可审计——天生适合需要跨语言、长期维护的 SDK。 我的实现过程</a> </h2> 起点：最小可用体（MVP）</a> </h3> 我给自己三条约束（大量使用 Coding Agent，统一由我把边界与审阅）： 基于 datamodel 生成 Pydantic 模型（pydantic.dev</a>）。</li> 实现最小 I/O（JSON-RPC over stdio）。</li> 迁移文档示例与基本测试，由我负责核对与回归。</li> </ol> 体量刻意保持小：先上线，尽快暴露问题。 迭代：从反馈中长出结构</a> </h3> 早期用户反馈“命名不一致、使用不顺手”。我让 agent 扫描文档生成 rename map（统一 Python 化命名），并对照其他语言实现取长补短： TypeScript SDK 里 helpers（降低重复样板）。</li> Go SDK 用 golden tests（固定请求/响应样张做回归）。</li> Rust SDK 的模块组织更克制。</li> 其他协议类 SDK（如 MCP</a>）采用相似的协议，值得借鉴。</li> </ul> 在 agent 协助下完成结构与测试重组，由我把控标准与审阅路径。 路由化：替代 if 判断</a> </h3> 我不想看到满屏的 if method == "..."</code>，于是写了极简路由，把“方法名 → 处理器”变成一等公民： builder = RouterBuilder() builder.request_attr(CLIENT_METHODS["fs_write_text_file"], WriteTextFileRequest, client, "writeTextFile") builder.request_attr(CLIENT_METHODS["fs_read_text_file"], ReadTextFileRequest, client, "readTextFile") </code></pre> 到 v0.4.9</code>，体量不大，但代码稳定且可教学。 上下文拣选：让 AI 吃对东西</a> </h2> 我把提示词上下文当“工程预算”管理：只喂必要信息、限定边界，并对版本负责。 上下文清单（manifest）：只列 schema、公共接口与最小示例；排除生成代码与外部依赖。</li> Diff 感知：只给改动的 hunk 与少量前后文（5–15 行），而不是整文件。</li> 黄金片段索引：提示 agent 自检索必要片段，避免大段粘贴。</li> 先立护栏：明确“不得臆造 schema 字段；失败优先；缺信息先询问”。</li> </ul> 方法论：Spec 与 AI 的协作</a> </h2> 原则</th> 说明</th></tr></thead> 生成与人工治理分离</td> 模型自动生成，业务由人编排与审阅，不混用。</td></tr> 从最小可用体开始</td> 用真实反馈驱动人体工学优化。</td></tr> Golden Test</td> 捕获/回放请求与响应，作为回归与审计基线。</td></tr> 上下文拣选与预算</td> 只喂必要上下文，小而准、可复现。</td></tr> </tbody></table> 规范给 AI 以边界；AI 让规范鲜活起来。 责任感：为什么我敢对 AI 写的代码负责</a> </h2> AI 能写，但边界我来定义。有强类型模型、可复现测试、可回放轨迹，我可以验证每一步。我信任的不是模型，而是它背后的工程纪律 。 我在 PR 里的说明</a> </h2> 这段说明最早见于 @xuanwo</a> 的 PR。我之前没有这样写，但我愿意采用这种方式——因为我对结果负责。在这个 SDK 的工作中我大量使用了 AI；边界与质量由我把关： This PR was primarily authored with GPT-5-Codex and hand-reviewed by me. I’m responsible for every change that lands here. </blockquote> 这不是“炫 AI”，而是结果负责的声明。 结语：速度与轨道</a> </h2> AI 是燃料，Spec 是轨道。燃料给你速度，轨道让你抵达。 我喜欢这种平衡：模型来写，我来设边界。每一行可解释，每一次失败可复现。这就是在人工智能时代负责任地构建方式。 — PsiACE （GitHub</a> · Apache OpenDAL PMC Member</a>） ACP：交互契约与 Python SDK 2025-09-08T00:00:00+00:00 TL;DR</a> </h2> ACP（Agent Client Protocol）是“客户端 ↔ 智能体”之间的交互契约，定义会话、内容块、工具调用、计划、文件系统等语义。</li> Zed 以 ACP 为核心，让内置与外部智能体共享同一套 UX，开发者只需实现一次协议即可通吃多个宿主。</li> 我写了 Python SDK：pip install agent-client-protocol</code>，提供 Pydantic 模型、AgentSideConnection</code>、stdio helper，帮你快速接上。</li> 这是一场标准化竞赛。ACP 与 MCP、A2A、AG-UI 互补又竞合，谁先积累生态谁就有话语权。</li> </ul> ACP 解决了什么</a> </h2> ACP 不只是“一条管道”，它规定： 传输层用 JSON-RPC，支持流式更新；</li> 会话生命周期（new/load/prompt/cancel）清晰；</li> 内容块支持文本、图片、音频、资源链接等；</li> 工具调用与更新（tool_call</code> / tool_call_update</code>）格式统一；</li> 文件读写、任务计划、状态同步都有规范字段。</li> </ul> 换句话说，宿主（如 Zed）与智能体之间的 UX 语义不再每家重造，体验可以搬家。 与其他标准的关系</a> </h2> AG-UI：同样关注交互层，部分语义重合，可能会出现“互转/共存”的场景。</li> MCP：负责工具和资源接入，适合与 ACP 搭配使用（工具能力来自 MCP，交互流程由 ACP 承载）。</li> A2A：聚焦智能体之间的通信，后续也可能与 ACP 对接。</li> </ul> Zed 的视角</a> </h2> 使用者：可以把 Claude Code、Gemini CLI、内部 Agent 统统接进编辑器，享受一致的流式体验和工具栏。</li> 开发者：写一次 ACP，就能跑在任何支持它的宿主上，减少重复 glue code。</li> 平台：通过协议锁定体验，生态统一，支持成本下降。</li> </ul> Python SDK 提供了什么</a> </h2> 安装： pip install agent-client-protocol </code></pre> 功能： Pydantic v2 模型：schema 都有类型提示；</li> AgentSideConnection</code> / ClientSideConnection</code>：分别处理智能体端与客户端；</li> stdio helper：适合 CLI/本地进程场景；</li> 与官方 schema 对齐，严格校验。</li> </ul> 最小 Echo Agent</a> </h3> import asyncio from acp import Agent, AgentSideConnection, stdio_streams from acp import InitializeRequest, InitializeResponse, NewSessionRequest, NewSessionResponse from acp import PromptRequest, PromptResponse, AuthenticateRequest, LoadSessionRequest, CancelNotification class EchoAgent(Agent): async def initialize(self, params: InitializeRequest) -> InitializeResponse: return InitializeResponse(protocolVersion=params.protocolVersion) async def newSession(self, params: NewSessionRequest) -> NewSessionResponse: return NewSessionResponse(sessionId="sess-1") async def loadSession(self, params: LoadSessionRequest) -> None: return None async def authenticate(self, params: AuthenticateRequest) -> None: return None async def prompt(self, params: PromptRequest) -> PromptResponse: return PromptResponse(stopReason="end_turn") async def cancel(self, params: CancelNotification) -> None: return None async def main() -> None: reader, writer = await stdio_streams() AgentSideConnection(lambda _conn: EchoAgent(), writer, reader) await asyncio.Event().wait() if __name__ == "__main__": asyncio.run(main()) </code></pre> Zed 侧 settings.json</code>： { "agent_servers": { "Echo Agent (Python)": { "command": "/abs/path/to/python", "args": ["/abs/path/to/echo_agent.py"], "env": {} } } } </code></pre> 打开命令面板输入 “dev: open acp logs” 可以调试序列化。 接下来</a> </h2> 补充更多示例：工具调用、文件交互、计划同步；</li> 与 MCP 结合，做端到端 demo；</li> 观察协议演进，及时跟进 schema 变更。</li> </ul> ACP 代表的是“交互语义的标准化”。当智能体要进主流工作流时，拥有统一契约就像当年云原生时代的容器、服务网格一样重要。Python SDK 的目标，就是让这件事变得简单，让反馈闭环先跑起来，再慢慢打磨。 Agent 没有秘密可言 2025-08-14T00:00:00+00:00 我是 PsiACE。最近我的工作主要围绕 Agent 与 RAG 展开：少谈玄学，多把闭环跑通，多让系统说得清楚、跑得稳定、可被回放与切换。 </blockquote> TL;DR</a> </h2> Agent 不是新宗教。它依然是事件、队列、CRUD 的工程实践，再加一层模型协作。</li> 共用一条 EventBus，把 agent.*</code> 与 huey.*</code> 事件打通；每条事件立即打印；最后用 Cascade 树复盘因果与时间。</li> 单文件 Demo，打开即跑：先看事件，后看因果，最后看结果。</li> </ul> 为什么写这个（以及为什么这么写）</a> </h2> 我不想再讨论"如何画出一个复杂的 Agent 架构图"。我更关心"如何让系统解释得清楚、失败得优雅、复盘得明白"。</li> 这篇文章附带一个单文件 Demo：共享总线、严格 ReACT、因果与时间合并呈现、即时可观测。开箱即用。</li> </ul> 我怎么做的</a> </h2> 核心设计原则</a> </h3> 共享 EventBus：Agent、ToolExecutor、Storage 都向同一条总线发事件。</li> 严格 ReACT：Thought → Action → Action Input → Observation → Final Answer。</li> 因果 + 时间：每轮用户输入推进 tick</code>；每次 Observation 再推进 tick</code>；Action → huey.* → Observation</code> 通过 parent-child 串起来。</li> 即时可观测：每条事件实时打印；最后用树形 Cascade Viewer 做分时复盘。</li> </ul> 事件流（概览）</a> </h3> 这和"传统架构"有什么不同？</a> </h2> 没有不同：事件、队列、CRUD，本来就在；只是把模型作为协作者接了进来。</li> 也不浮夸：没有"智能"也不会失效的设计；它可靠、可解释，也更容易落地。</li> </ul> 极简骨架（节选）</a> </h2> Event-driven storage wrapper</a> </h3> class EventureMemoryStorage(MemoryStorage): def __init__(self, event_bus: EventBus): super().__init__("huey") self.bus = event_bus def enqueue(self, data, priority=None): super().enqueue(data, priority=priority) self.bus.publish("huey.queue.enqueue", { "data": data, "priority": priority }) </code></pre> Tool with self-description</a> </h3> def tool_echo(params: dict) -> dict: """Echo back text. Args: {"text": string} Returns: {"ok": bool, "echo": string}""" return {"ok": True, "echo": str(params.get("text", ""))} </code></pre> ReACT loop（核心思想）</a> </h3> while True: resp = client.chat.completions.create(model=model, messages=history) assistant = resp.choices[0].message.content or "" call = extract(assistant) if call: action_id = uuid4() bus.publish("agent.action", {"id": action_id, **call}) # wait for agent.observation(id==action_id) and append as Observation continue return assistant </code></pre> 我遵循的几个原则</a> </h2> 先闭环，后花活：先把"事件→队列→状态变化→ReACT"打通，再谈优化。</li> 因果与时间是工程的一等公民：tick 表达更新周期；parent-child 表达触发链。</li> 可观测性优先：当系统能解释自己，优化才有基础。</li> 可替换：总线稳定，后端可换（内存→Redis），模型可换（供应商/版本）。</li> </ul> 如何运行（单终端）</a> </h2> 代码位置</a> </h3> 请点击【阅读原文】跳转： agent_has_no_secret.py</a></li> README.md</a></li> </ul> 运行步骤</a> </h3> 配置 .env</code>（OpenRouter 推荐；OpenAI 也可）</li> python agent_has_no_secret.py</code></li> </ol> 你将看到什么</a> </h3> 实时事件流：user.input</code>、agent.thought</code>、agent.action</code>、huey.data.*</code>、agent.observation</code> …</li> 绿色的 Final Answer 面板</li> 按 tick 分组的树形 Cascade Viewer：在 agent.action</code> 下能看到 huey.data.*</code> 与 agent.observation</code> 的父子层级</li> </ul> 写在最后</a> </h2> 我更钦佩能把东西"说清楚、跑起来"的工程师。Agent 没有秘密可言： 先把闭环打通，再考虑花活；</li> 先让因果与代价可见，再谈"更聪明"。</li> </ul> Baby Steps: 用 Python 实现一个能自举的 Coding Agent 2025-07-16T00:00:00+00:00 Bub 的第一个 milestone：自动修类型注解。由 Moonshot K2 驱动 Bub: Successfully fixed the first mypy issue by adding the missing return type annotation -> None</code> to the __init__</code> method in src/bub/cli/render.py</code>, reducing the error count from 24 to 23. </blockquote> 1. 为什么要自己造 Agent？</a> </h2> Coding Agent 现在已经是个红海赛道，市面上有不少优秀的产品，比如 yetone 的 avante.nvim、晋涛哥哥推荐的 AmpCode，还有许多团队在 PPT 中绘制宏伟蓝图。然而，Coding Agent 的“token 大力出奇迹”现象也很明显——动辄几十万 token 的消耗，真正有价值的部分却少之又少。这让我很好奇：如果自己动手造一个 Coding Agent，能不能找到更高效、更实用的解决方案？ 于是，我开始折腾一个叫 Bub 的 CLI 助手。它的目标很简单：做一个命令行下的实用助手，同时具备有限的自举能力。自举这个概念在编译器、操作系统领域早已不算新鲜，很多 Coding Agent 也喜欢宣传“AI 工程师贡献了多少代码”。我希望 Bub 能迈出自己的第一步，解决它自身代码中的第一个实际问题。 2. 最小可用：先跑起来再说</a> </h2> 我的经验是，能跑起来的最小闭环最重要，别一上来就追求“完美架构”或者花太多时间做数据小偷。 Bub 的分层很简单： Agent：主循环，负责 LLM 交互、工具调用、上下文管理。</li> Tool：每个工具一个类，参数用 Pydantic 校验。</li> ToolRegistry：注册所有工具，方便扩展。</li> CLI：Typer + Rich，命令行入口，支持展开中间状态。</li> </ul> Agent 的本质其实就是一个 while 循环。每次循环，Agent 会根据当前上下文判断是否需要调用工具，如果需要就调用，然后把工具的返回结果写回上下文。 主循环核心代码</a> </h3> class Agent: def chat(self, message: str) -> str: self.conversation_history.append(Message(role="user", content=message)) while True: # 构造上下文，历史消息+工具列表 ... response = litellm.completion(...) assistant_message = str(response.choices[0].message.content) self.conversation_history.append(Message(role="assistant", content=assistant_message)) tool_calls = self.tool_executor.extract_tool_calls(assistant_message) if tool_calls: for tool_call in tool_calls: result = self.tool_executor.execute_tool(tool_call.name, **tool_call.parameters) observation = f"Observation: {result.format_result()}" self.conversation_history.append(Message(role="user", content=observation)) continue else: return assistant_message </code></pre> 踩过的坑： 没有捕获，LLM 输出格式一变就死循环</li> 工具参数没校验，LLM 乱传参数直接崩</li> Observation 反馈太长或缺乏有效信息，LLM 理解困难</li> </ul> 3. 工具定义：扩展 LLM 的能力</a> </h2> 工具是 LLM 和外部世界的桥梁，定义得好，模型才能真正“动手”。我的做法是： 工具参数全部用 Pydantic 校验，类型不对直接拒绝。</li> 命令行工具有黑名单（比如 rm</code>、del</code>），遇到危险命令直接报错。</li> 工具执行结果结构化返回，别让 LLM 猜。</li> 操作命令行工具时，stdout 和 stderr 都很重要，不能只给 exit code。</li> 工具之间要有明确边界，避免混淆。</li> </ul> class RunCommandTool(Tool): DANGEROUS_COMMANDS = {"rm", "del"} def _validate_command(self, base_cmd: str) -> Optional[str]: if base_cmd in self.DANGEROUS_COMMANDS: return f"Dangerous command blocked: {base_cmd}" def execute(self, context: Context) -> ToolResult: # 校验命令，执行并返回结果 </code></pre> 4. Prompt 设计：让 LLM 按套路出牌</a> </h2> 组织良好的提示词能显著提升 LLM 的输出质量。对于 Coding Agent 来说尤其重要，因为 LLM 的输出格式很容易失控。 我的经验： Prompt 里要列出所有工具和参数 schema。</li> 多给几个调用示例，覆盖常见用法。</li> Observation 反馈要简洁，别堆无用信息。</li> </ul> Bub 的 ReAct Prompt 结构： You are an AI assistant with access to tools. When you need to use a tool, follow this format: Thought: ... Action: run_command Action Input: {"command": "ls"} Observation: <output> ... Final Answer: <your answer> </code></pre> ReAct 的好处是简单直接，容易落地，虽然 token 消耗大，但能快速试错、跨模型迁移。 5. milestone：自动修类型注解</a> </h2> 定义好 Agent Loop、工具和 Prompt 后，Bub 的第一个 milestone 就是自动修复了一个 mypy 报错。 比如： - def __init__(self): - self.console = Console() - self._show_debug = False + def __init__(self) -> None: + self.console: Console = Console() + self._show_debug: bool = False </code></pre> 实际的 Agent Loop： 只让 agent 改类型注解、格式化、重命名，别让它碰复杂逻辑。</li> 先用命令行工具执行 mypy</code>，拿到报错信息。</li> 让 agent 生成修复建议，再用 file edit 工具应用到代码。</li> 修完自动再跑一次 mypy，确保没新问题。</li> </ul> 踩过的坑： 模型对代码上下文理解有限，经常修错。</li> 不验证，bug 越修越多。</li> </ul> 6. 进阶玩法与工程自查</a> </h2> 随着功能扩展，踩的坑也越来越多。我的一些经验： 工具扩展时，建议单一职责，参数 schema 明确。</li> 长对话要截断或摘要，别让 LLM 超窗。</li> 生产环境建议沙箱/虚拟机，命令行工具默认禁危险命令。</li> LLM 输出格式不稳时要有 fallback 兜底。</li> </ul> 7. 总结</a> </h2> Bub 还在早期，但已经能帮我自动修 bug、跑命令、读写文件。我希望这只是一个开始，然后得到更多有意思的反馈。 参考资料</a> </h3> How to Build an Agent (ampcode)</a></li> Tiny Agents: Building LLM-Powered Agents from Scratch (HuggingFace)</a></li> Bub: Bub it. Build it.</a></li> </ul> 让 LlamaIndex 接上 Cloudflare AI Gateway 2025-07-11T00:00:00+00:00 为什么折腾这个</a> </h2> 单供应商的 LLM 太脆弱：OpenAI 宕机、Anthropic 限流，就等于业务停摆。Cloudflare AI Gateway 给了一个诱人的承诺： 多家模型的统一入口；</li> 内置缓存、限流、熔断；</li> 请求失败自动切换。</li> </ul> 问题是，LlamaIndex 的 LLM 调用直接命中各家 API，没法自适应 Gateway。我需要一个中间层，让原有代码不改，直接享受多云编排。 解决方案</a> </h2> 写了一个轻量 wrapper： from llama_index.llms.cloudflare_ai_gateway import CloudflareAIGateway from llama_index.llms.openai import OpenAI from llama_index.llms.anthropic import Anthropic openai_llm = OpenAI(model="gpt-4o-mini", api_key="your-key") anthropic_llm = Anthropic(model="claude-3-5-sonnet", api_key="your-key") gateway_llm = CloudflareAIGateway( llms=[openai_llm, anthropic_llm], account_id="your-cloudflare-account-id", gateway="your-gateway-name", api_key="your-cloudflare-api-key", ) resp = gateway_llm.chat([ChatMessage(role="user", content="2 + 2 = ?")]) </code></pre> 作用就是：截住 LlamaIndex 发出的请求，改写为 Cloudflare 期待的格式，处理返回值。原始业务代码不用动。 能做什么</a> </h2> 顺序尝试多个模型，失败自动换下一个；</li> 支持 Cloudflare 的流式接口、异步调用；</li> 统一注入鉴权、重试、日志；</li> 经过实测的模型：OpenAI、Anthropic；</li> 理论兼容：Google AI Studio、DeepSeek、Grok、Azure OpenAI、Perplexity、Replicate 等。</li> </ul> 如何体验</a> </h2> PR 在提审（#19395</a>），不过代码已经能跑： git clone <repo> cd llama-index-llms-cloudflare-ai-gateway pip install -e . export OPENAI_API_KEY=... export ANTHROPIC_API_KEY=... export CLOUDFLARE_ACCOUNT_ID=... export CLOUDFLARE_API_KEY=... export CLOUDFLARE_GATEWAY=... uv run pytest tests/ </code></pre> 注意事项</a> </h2> Cloudflare 虽然提供 OpenAI 兼容接口，但做中间层能解锁更多功能（自定义头、特定路由、日志追踪）。</li> 多模型编排别忘了考虑一致性：模型切换后回答风格可能不同，需要在应用层消化。</li> 缓存命中率很依赖 prompt 规范，必要时结合 embedding 去重。</li> </ul> 这个封装的意义不在于“又造了个轮子”，而是告诉你：在 LlamaIndex 体系里，替换底层 LLM 客户端是很容易的。运维侧想要多云容灾、成本优化，只需要写一个薄薄的适配层。 用 WebAssembly 为 Code Agent 范式构建安全沙箱 2025-07-08T00:00:00+00:00 Code Agent（代码代理范式）的能力令人惊叹，但安全性问题同样令人担忧。在我测试第一个 Code Agent 时，它很快就尝试安装包、访问环境变量，甚至想要读取系统文件。我们需要一个真正安全的执行环境。 安全挑战</a> </h2> 代码执行型 AI 代理（Code Agent 范式）确实能完成很多任务——数据分析、数学计算、代码调试。但它们缺乏对系统边界的认知，可能带来严重的安全风险。 典型的安全威胁场景： 权限越界：尝试访问 /etc/passwd</code>、系统环境变量</li> 恶意包安装：从被污染的 PyPI 源安装恶意包</li> 资源耗尽：无限循环、内存泄漏导致系统崩溃</li> 网络攻击：发起 DDoS、端口扫描等恶意行为</li> </ul> 像 Hugging Face smolagents</a> 之类的项目已经意识到了这个问题，提供了多种执行器选项来平衡功能性和安全性。 WebAssembly 的安全优势</a> </h2> WebAssembly 的核心价值不在于性能，而在于原生安全设计。作为从浏览器安全模型发展而来的技术，WASM 提供了： 能力安全模型：基于最小权限原则，只能访问明确授权的资源</li> 细粒度资源控制：精确监控 CPU 使用、内存分配、网络访问</li> 执行确定性：相同的输入总是产生相同的输出，便于审计</li> 语言无关性：支持多种编程语言的安全执行</li> </ol> Simon Willison 在他的 TIL 文章</a> 中详细探讨了这个方案，Hacker News 社区也有深入讨论</a>。 虽然 Hugging Face smolagents</a> 已经提供了基于 Pyodide 和 Deno 的 WasmExecutor</code>，但我想探索一个基于 wasmtime 的本地执行方案，看看有什么不同的技术权衡。 技术实现</a> </h2> 基于 wasmtime-py 和 VMware 的 Python WASM 运行时，我实现了一个简单的沙箱执行器： from wasmtime_executor import WasmtimePythonExecutor from smolagents import CodeAgent, InferenceClientModel class WasmtimeCodeAgent(CodeAgent): def create_python_executor(self): return WasmtimePythonExecutor( additional_authorized_imports=self.additional_authorized_imports, max_print_outputs_length=self.max_print_outputs_length, **self.executor_kwargs, ) agent = WasmtimeCodeAgent( tools=[], model=InferenceClientModel(), additional_authorized_imports=["math", "json"], ) result = agent.run("Calculate the square root of 125") </code></pre> 核心实现思路：利用 VMware 提供的 Python WASM 二进制文件，通过 wasmtime-py 进行运行时管理，并实现与 smolagents 的兼容层。关键的技术差异在于本地执行，避免了对外部 Deno 运行时的依赖。 技术评估</a> </h2> 优势方面： 与 smolagents 框架的无缝集成</li> 基础 Python 操作的良好支持</li> 完善的错误处理和异常捕获</li> 执行状态的有效隔离和持久化</li> 本地化部署，减少网络依赖</li> </ul> 技术权衡： 安全隔离 vs Python 生态系统限制</li> 执行安全性 vs 性能开销</li> 确定性执行 vs 配置复杂性</li> 本地控制 vs 远程服务调用</li> </ul> 生产就绪性</a> </h2> 当前状态：实验性项目。这个实现主要用于概念验证和技术探索。 生产环境部署需要解决的关键问题： 资源限制和配额管理</li> 包依赖管理和安全扫描</li> 性能优化和缓存策略</li> 完整的审计日志和监控</li> 安全漏洞的持续评估</li> </ul> 但对于技术研究、原型验证、理解安全边界？这个实现提供了很好的起点。 技术价值</a> </h2> 这个项目的真正价值不在于具体的实现代码，而在于证明了Code Agent 范式存在多种安全沙箱方案。虽然 smolagents 提供了基于 Pyodide 的 Deno 沙箱，wasmtime 为本地执行提供了另一种技术选择。开发者可以基于现有的代理框架，添加安全边界，保持功能完整性，同时探索不同的技术权衡。 进一步探索</a> </h2> 完整的实现代码和详细文档在我的 Wasmtime 执行器项目</a> 中。代码虽然粗糙，但功能完整。欢迎克隆、测试、改进。 理解 Code Agent 范式安全挑战的最佳方式就是动手实践。即使是简单的概念验证项目，也能带来深刻的技术洞察。 参考资料</a> </h2> Hugging Face smolagents</a></li> Wasmtime 执行器项目</a></li> Simon Willison 的 WASM Python 沙箱</a></li> VMware WebAssembly 语言运行时</a></li> </ul> 当 RAG 遇上编程助手 2025-06-18T00:00:00+00:00 我的日常工作是和 RAG 打交道，最近 Coding Agent 大热，Claude Code 、Cursor 这样的工具已经成为了研发必备的效率神器，于是尝试调研和学习了一下，抛砖引玉。 </blockquote> TL;DR</a> </h2> Coding Agent 中其实不少环节都可以用到 RAG（检索增强生成），把"查资料"和"写代码"这两件事结合起来。具体来说： 理解你想干什么：分析需求，找到相关代码和文档</li> 快速定位文件：在大项目里找到关键模块</li> 写出合适的代码：基于实际情况和最佳实践</li> 帮你调试：分析错误，搜索解决方案</li> </ul> 说白了，就是让编程助手从"代码生成器"变成真正的"软件工程师"。 写代码的真实痛点</a> </h2> 作为一个软件工程师，大部分时间我们都在干这些事： 搞懂一个巨大项目是怎么工作的</li> 在几百个文件里找到那个该死的模块</li> 看着莫名其妙的报错发呆</li> 学新框架新工具</li> </ul> 这些事情真的很烦，也很费时间。Coding Agent 应该帮我们处理这些重复劳动，让我们可以自由表达自己的想法。假如你的 “编程搭子” 还不够聪明，理解不了你的代码，找不到对的信息，那几乎只会搞砸一切，更别说帮你调试了。 Coding Agent 到底是什么</a> </h2> 想象一下，你要做一个从没做过的功能。通常你会这样： 先 Google 找例子</li> 翻框架文档</li> 在自己项目里搜类似的代码</li> 上 StackOverflow 看看别人怎么解决的</li> </ul> Coding Agent 就是一个可以自主执行这些动作的智能体，或者说把这个过程自动化了。它不仅可以充当搜索引擎进行学习，还能把找到的信息组合起来，帮你写代码。 原理其实很简单： 检索（Retrieval）：找相关的东西——代码、文档、问答</li> 生成（Generation）：用这些信息写出新的代码或解决方案</li> </ol> 就这两步，但效果比单纯的代码生成器强多了。 当然，为了让一切更加顺利，还需要添加反馈机制。根据调试信息优化并进行修正。 </blockquote> RAG 怎么让编程助手变聪明</a> </h2> 结合 RAG，编程助手就能处理我们平时遇到的各种问题了。 整个过程大概是这样的： 1. 搞清楚你要干什么</a> </h3> 你说"给 API 加个用户认证"，助手得先理解： 要 JWT、OAuth 还是别的方案？</li> 现有代码哪里需要改？</li> 你用的什么框架？</li> </ul> 然后开始工作——去翻文档找例子，把你的需求搞清楚。 2. 收集相关资料</a> </h3> 然后就是搜集阶段，像个勤快的实习生一样，到处找： 官方文档：框架的使用指南</li> 代码例子：你项目里或者开源项目的类似实现</li> 社区问答：StackOverflow、GitHub 上的讨论</li> 最佳实践：编码规范和安全建议</li> </ul> 把这些都混在一起，就是传说中的"知识汤"。 3. 写代码并测试</a> </h3> 有了这些资料，助手就能写出比较靠谱的代码了。但它不会直接给你，而是先在沙箱里跑一遍： 看看有没有明显的错误</li> 确认确实能解决你的问题</li> 有问题的话马上调整</li> </ul> 4. 处理成功和失败</a> </h3> 代码跑通了当然好，但如果出错了，它不会放弃： 分析错误信息</li> 去找类似问题的解决方案</li> 用新信息再试一遍</li> </ul> 这个循环让 Coding Agent 变得靠谱多了。 5. 交付成果</a> </h3> 最后，助手会把完整的解决方案给你——不只是代码，还有说明文档。 最大的坑：什么时候去查资料？</a> </h2> 用 RAG 有个很关键的问题：什么时候该去查资料？ 太早查可能漏掉重要信息，太晚查又会拖慢速度。我觉得这样比较合理： 通用的东西（框架文档、编码规范）提前准备好</li> 具体问题（调试、特殊需求）现查现用</li> </ul> 这样既不会太慢，也不会出错。 什么信息该存，什么该丢</a> </h2> 不是所有信息都一样重要。有些东西（比如框架规则）得一直记着，有些（比如这次运行的日志）用完就可以扔了。 这样处理可能会是一个不错的路线： 知识类型</th> 怎么存</th> 怎么找</th></tr></thead> 编码规范</td> 一直存着</td> 知识图谱快速查找</td></tr> 文档教程</td> 按版本存</td> 语义搜索相关部分 + 代码结构映射</td></tr> 问答和代码库</td> 先临时后永久</td> API 查询 + 缓存</td></tr> 运行时反馈</td> 临时存储</td> 即时检索和更新</td></tr> </tbody></table> 这样既不会太慢，也不会占太多空间。 执行的上下文越长，无效的信息越多，也需要及时压缩和截断，保留真正有效的部分。 </blockquote> 想试试的话，从简单开始</a> </h2> 如果你也想写个编程助手，但不想搞得太复杂，可以这样开始： 先写一些规则和提示词</li> 用简单的搜索工具找文档</li> 写个脚本查 StackOverflow</li> 用 grep</code>、lint</code> 这些工具收集反馈</li> </ol> 这样就有个基础版本了，后面再慢慢改进。 写在最后</a> </h2> Coding Agent 确实在改变编程的方式。它把"查资料"和"写代码"结合起来，让编程助手真正能帮上忙——理解你的需求、找到相关文件、写出能用的代码、帮你调试问题。 不管你是新手还是老手，这些效率工具总归能让工作轻松一些。如果你想自己搞一个，建议从简单的开始，慢慢试验。反正现在这个领域变化很快，说不定你就能做出下一个爆款工具。 总之，这个方向还是很有意思的，值得关注。 RAG 没有捷径 2025-04-17T00:00:00+00:00 去年我从数据库基础设施跳进 RAG 项目时，以为终于能摆脱底层细节，结果是另一种更复杂的基础设施扑面而来。RAG 看似应用层，其实处处是工程化的坑。 检索：不只是“找到”</a> </h2> 传统搜索里，我们调索引、调排序，指标相对稳定。RAG 的检索要面对的是语义空间——向量近邻、模型偏差、上下文漂移。今天 QA 能命中“三季度发货策略”，明天可能因为语境不同完全跑偏。检索的目标从“找到哪条记录”变成“理解用户真正想说什么，并确保返回的语段能支撑后续推理”。 Agent：别被名字骗了</a> </h2> 大家给 Agent 起了很多酷炫的名字：规划代理、推理代理、工具代理……但它们大多还是条件语句堆出来的工作流。区别只是条件不是硬编码，而是 LLM 动态生成。重点不在“更智能”，而在“如何把工具、状态、反馈闭环结构化”。我们需要的是一个可观察、可替换的流程引擎，模型只是其中的决策组件。 Grounding Truth：最后的锚点</a> </h2> 没有扎实的事实校验，RAG 系统只是会讲好听故事的随机鹦鹉。Grounding 不是选配，而是价值锚定。你得持续补充可验证的知识底座，让领域专家参与反馈循环，设计清晰的“证据链”输出格式。否则，Agent 再聪明也只是在幻觉上做推理。 复杂性从哪里来</a> </h2> 数据形态多样：PDF、截图、音视频、传感器数据同时存在，且要保持语义一致。</li> 一致性概念模糊：知识会被实时更新，旧答案随时过期。你需要定义“足够新”“足够可信”的标准。</li> 成本与体验拉扯：检索准确度、上下文长度、延迟、推理深度，一环牵动一环。</li> </ul> 这比建一个数据库、一个 API 难多了，但也更有意思。 为什么还要干</a> </h2> 因为我们在重新定义“信息系统”： 让系统理解人的意图，而不是死背关键词；</li> 让工具链能自我学习、自动拼装；</li> 把抽象的语言推理和现实世界的事实连接起来。</li> </ul> 这是一种新的基础设施：检索、智能体与真实感三元同构。谁能把这三者编排好，谁就掌握下一代知识系统的主动权。 所以，当别人问我为什么离开数据库领域去做 AI 应用时，我会说：“我没离开基础设施，我只是换了一种方式去构建它。” 现在，请允许我回去调向量量化、训几个不听话的 Agent，并确保文本切分策略不会把事实撕裂。这，就是日常的 RAG 工程。 NebulaGraph MCP Server 正式开源！探索 AI+图数据库无限可能 2025-03-11T00:00:00+00:00 一、背景</a> </h2> 过去几周，Model Context Protocol (MCP) 在技术社区中引发了广泛的讨论和关注。借此机会，我参与了几个相关的开源项目，包括为 LlamaIndex 官方仓库贡献了 McpToolSpec 实现，以及和 Xuanwo、FrostMing 合作开发了一版 Model Context Protocol Server for Apache OpenDAL™。 MCP 是目前唯一一个在生态上具有优势的标准。在这一背景下，我们基于 NebulaGraph 3.x 实现了一个简单的 NebulaGraph MCP Server，作为 NebulaGraph X MCP 生态中的第一个基础组件，供大家探索 AI 与图数据库结合的可能性，希望能够看到更多在这个模式下的有趣工作。 二、Model Context Protocol (MCP)</a> </h2> MCP 是由 Anthropic 团队推出的一项开放协议，旨在为 AI 系统提供统一的、高效的方式访问多种数据资源。通过采用客户端-服务器架构，MCP 将数据访问标准化，解决了传统 AI 系统在不同数据源之间的碎片化问题。 MCP 核心特点</a> </h3> 标准化的通信方式：通过 MCP，AI 助手能够有效地访问各种数据源，比如本地数据、远程服务和企业工具。</li> 开放性与生态优势：目前 MCP 社区中已有近 1000 个 MCP Server 实现，覆盖搜索、天气、数据库等多个领域，支持工具的快速接入。</li> 灵活的架构：通过定义客户端和服务端的交互协议，MCP 为开发者提供了构建可扩展、可复用系统的基础。</li> </ol> 虽然目前在安全性和可靠性上仍有一些挑战，但随着协议规范的完善和成熟开发模式的引入，这些问题将逐步得到解决。 三、NebulaGraph MCP Server 功能</a> </h2> 由于最近一段时间一直围绕 GraphRAG 和 Agentic Workflow 做一些工作，利用大模型和智能体进行图上数据的洞见和挖掘是一个非常重要的议题。为此，我快速开发了 NebulaGraph MCP Server，以支持 NebulaGraph 3.x 作为工具接入 MCP 生态，供语言模型（如 Claude、GPT 等）调用和使用。 目前 NebulaGraph MCP Server 基于 FastMCP 实现，遵循 MCP 的核心规范，旨在提供高效、轻量的图数据库连接服务。 通过将 NebulaGraph 的功能暴露为标准化的工具接口，该 Server 能够让大模型轻松调用 NebulaGraph 数据，实现简单的图探索任务。 多种传输方式：支持 stdio 和 SSE 两种传输模式，满足不同开发和部署场景的需求。</li> </ul> </li> 基础图探索能力：图空间（Graph Space）列出：允许模型查询可用的图空间。</li> 模式（Schema）查询：支持查询指定图空间的模式定义。</li> 查询执行（Query Execution）：支持通过 MCP Server 执行 NebulaGraph 查询。</li> </ul> </li> 内置算子模板：实现了路径搜索和邻居发现等常用操作的模板，方便语言模型按需调用这些工具，快速获取图数据的初步洞察（Insight）。</li> </ul> </li> </ul> 为了展示它的效果，我基于 LlamaIndex 中的 McpToolSpec 和 ReActAgent 构建了一个简单的示例，下面是对应的截图： 四、结语</a> </h2> NebulaGraph MCP Server 是对 MCP 生态的一个初步尝试，旨在为语言模型和图数据库的结合提供一个起点。随着协议的逐步成熟和生态的扩展，我们期待它能够在更多真实场景中发挥价值。如果您对这一方向感兴趣，欢迎一起探索、尝试！ 把 MCP 工具塞进 LlamaIndex 工作流 2025-02-11T00:00:00+00:00 一、前言</a> </h2> 本文主要介绍了如何将 MCP（Model Context Protocol，模型上下文协议）工具转换为可以直接使用的 LlamaIndex 工具，使 LlamaIndex 用户能像使用 Claude, Cursor 等现代 AI 应用一样无缝集成这些服务。 二、技术背景</a> </h2> 2.1 什么是 MCP 协议？</a> </h3> MCP（模型上下文协议，https://modelcontextprotocol.io）是面向 AI 应用交互的服务构建协议。开发者可通过该协议构建具备数据资源（resources）、功能工具（tools）和提示模板（prompts）的服务端点。例如，我们可以定义获取 IP 详细信息的 fetch_ipinfo 工具： @mcp.tool() async def fetch_ipinfo(ip: str | None = None, **kwargs) -> IPDetails: """获取指定IP的详细信息 参数: ip(str or None): 目标 IP 地址，格式如 192.168.1.1 **kwargs: 传递给 IPInfo 处理器的附加参数 返回: IPDetails: 包含城市、时区等信息的结构化数据 """ handler = ipinfo.getHandler( access_token=os.environ.get("IPINFO_API_TOKEN"), headers={"user-agent": "basic-mcp-server"}, **kwargs, ) details = handler.getDetails(ip_address=ip) return IPDetails(**details.all) </code></pre> 2.2 LlamaIndex 框架特征</a> </h3> LlamaIndex（https://github.com/run-llama/llama_index）是构建知识索引系统的核心框架，其核心价值在于将外部信息结构化地接入大语言模型，实现高效的信息检索、智能问答和对话生成。当需要集成动态数据源时，将 MCP 工具转换为 LlamaIndex 工具成为关键技术需求。 在 LlamaIndex 中，NebulaGraph 已经有两种方法实现 GraphRAG：KnowledgeGraphIndex 用来对任何私有数据从零构建知识图谱（基于 LLM 或者其他语言模型），再 4 行代码进行 Graph RAG： graph_store = NebulaGraphStore( space_name=space_name, edge_types=edge_types, rel_prop_names=rel_prop_names, tags=tags, ) storage_context = StorageContext.from_defaults(graph_store=graph_store) # Build KG kg_index = KnowledgeGraphIndex.from_documents( documents, storage_context=storage_context, max_triplets_per_chunk=10, space_name=space_name, edge_types=edge_types, rel_prop_names=rel_prop_names, tags=tags, ) kg_query_engine = kg_index.as_query_engine() </code></pre> KnowledgeGraphRAGQueryEngine 则可以在任何已经存在的知识图谱上进行 GraphRAG: graph_store = NebulaGraphStore( space_name=space_name, edge_types=edge_types, rel_prop_names=rel_prop_names, tags=tags, ) storage_context = StorageContext.from_defaults(graph_store=graph_store) graph_rag_query_engine = KnowledgeGraphRAGQueryEngine( storage_context=storage_context, ) </code></pre> 三、为什么需要将 MCP 集成至 LlamaIndex</a> </h2> 在实际 AI 应用开发中，集成 MCP 工具主要解决以下需求： 功能复用：利用现有 MCP 生态（项目列表见 https://github.com/AlexMili/Awesome-MCP）快速扩展系统能力</li> 流程统一：建立标准化工具调用范式，简化大模型对外部 API 的调用复杂度</li> 自动化管理：通过自动转换机制实现 MCP 工具到 LlamaIndex FunctionTool 对象的映射，便于 Agent 自动调度</li> </ul> 该集成方案可以有效降低开发成本，同时发挥 LlamaIndex 在上下文管理和对话生成方面的优势。 四、技术实现方案</a> </h2> 实现流程包含三个关键阶段： MCP 服务通信：通过 MCPClient 类建立服务连接，支持工具发现（list_tools）和调用执行（call_tool）</li> 适配器构建：定义 MCPToolAdapter 类，将 MCP 工具元数据转换为 LlamaIndex 的 FunctionTool 对象</li> 智能代理集成：在 LlamaIndex Agent 中加载转换后的工具，实现自动化调用</li> </ul> 五、核心代码解析</a> </h2> 协议转换适配器</a> </h3> from llama_index.core.tools import FunctionTool from pydantic import create_model, BaseModel class MCPToolAdapter: def __init__(self, client): self.client = client async def list_tools(self): tools = await self.client.list_tools() return [ FunctionTool.from_defaults( fn=self._create_tool_fn(tool.name), name=tool.name, description=tool.description, fn_schema=self._create_pydantic_model(tool.schema), ) for tool in tools ] def _create_pydantic_model(self, json_schema): # 实现JSON Schema到Pydantic模型的动态转换 ... </code></pre> 类型系统映射</a> </h3> JSON_TYPE_MAPPING = { "string": str, "number": float, "integer": int, "boolean": bool, "object": dict, "array": list } def create_dynamic_model(schema): fields = {} for name, prop in schema["properties"].items(): py_type = JSON_TYPE_MAPPING[prop["type"]] if name in schema.get("required", []): fields[name] = (py_type, Field(...)) else: fields[name] = (Optional[py_type], Field(None)) return create_model("DynamicModel", **fields) </code></pre> 服务调用封装</a> </h3> async def fetch_ipinfo_wrapper(**kwargs): return await mcp_client.call_tool("fetch_ipinfo", kwargs) </code></pre> 关键技术创新点</a> </h3> 动态模式转换：实现 JSON Schema 到 Pydantic 模型的运行时转换，保证参数校验的严格性</li> 异步调用管道：基于 Python asyncio 构建非阻塞式服务调用，提升工具执行效率</li> 协议抽象层：通过适配器模式解耦 MCP 协议与 LlamaIndex 框架，保证系统扩展性</li> </ul> 将 MCP 工具的输入参数转换为 Pydantic 模型的原因在于：MCP 工具使用 JSON Schema 格式定义输入参数（在工具对象的 inputSchema 中，类型为 Dict[str, Any] ），而 create_model_from_json_schema 函数将其转换为 Pydantic 模型，该模型用作 LlamaIndex 中 FunctionTool 的 fn_schema。 六、LlamaIndex 中的 MCP 工具调用实践</a> </h2> 以下代码来自 llamaindex_mcp_example.py，完整展示了 MCPToolAdapter 与 LlamaIndex 的集成方式： import os from llama_index.core.llms import ChatMessage from llama_index.core.agent import ReActAgent, ReActChatFormatter from llama_index.core.agent.react.prompts import REACT_CHAT_SYSTEM_HEADER from llama_index.llms.azure_openai import AzureOpenAI from llamaindex_mcp_adapter import MCPToolAdapter from mcp_client import MCPClient import anyio import dotenv import argparse dotenv.load_dotenv() # 系统级指令模板 SYSTEM_PROMPT = """\ 您是一个智能法律助手 在回答用户问题前，必须通过IP信息确认用户所在司法管辖区 操作规则： - 当涉及地理位置、时区等问题时，自动调用fetch_ipinfo工具 - 法律咨询类问题需结合IP所在国家/地区法律体系 """ async def get_agent(adapter: MCPToolAdapter): """智能代理初始化函数""" tools = await adapter.list_tools() # 获取MCP工具列表 # 配置Azure OpenAI大语言模型 llm = AzureOpenAI( model=os.environ.get("AZURE_OPENAI_MODEL", "gpt-4"), max_tokens=int(os.environ.get("AZURE_OPENAI_MAX_TOKENS", 4096)), azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"), api_key=os.environ.get("AZURE_OPENAI_API_KEY"), api_version=os.environ.get("AZURE_OPENAI_API_VERSION"), engine=os.environ.get("AZURE_OPENAI_ENGINE") ) # 构建ReAct智能代理 agent = ReActAgent.from_tools( llm=llm, tools=list(tools), react_chat_formatter=ReActChatFormatter( system_header=SYSTEM_PROMPT + "\n" + REACT_CHAT_SYSTEM_HEADER, ), max_iterations=20, # 限制最大推理步数 verbose=True # 启用详细日志 ) return agent async def handle_user_message(message_content: str, agent: ReActAgent): """消息处理流水线""" user_message = ChatMessage.from_str(role="user", content=message_content) response = await agent.achat(message=user_message.content) print(f"[智能代理响应] {response.response}") if __name__ == "__main__": async def main(): # 命令行参数解析 parser = argparse.ArgumentParser() parser.add_argument("--client_type", choices=["sse", "stdio"], default="stdio", help="连接模式：sse(Server-Sent Events)或stdio(标准输入输出)") args = parser.parse_args() # MCP客户端初始化 if args.client_type == "sse": client = MCPClient("http://0.0.0.0:8000/sse") # SSE长连接模式 else: client = MCPClient( # 子进程模式 "./venv/bin/python", ["mcp_server.py", "--server_type", "stdio"] ) # 工具适配器初始化 adapter = MCPToolAdapter(client) agent = await get_agent(adapter) # 执行测试用例 await handle_user_message("我的IP所在城市是哪里？", agent) await handle_user_message("持有大麻在我国是否合法？", agent) anyio.run(main) # 启动异步运行时 </code></pre> 关键实现解析</a> </h3> 工具获取机制：通过 adapter.list_tools() 动态加载 MCP 服务端注册的工具列表</li> 自动将每个 MCP 工具转换为 LlamaIndex 的 FunctionTool 对象</li> </ul> </li> 智能代理配置：使用 Azure OpenAI 作为底层大语言模型引擎</li> 集成 ReAct 推理框架，支持多步工具调用</li> 设置 20 步的最大推理深度防止无限循环</li> </ul> </li> 消息处理流程：将用户输入封装为标准化 ChatMessage</li> 通过 agent.achat() 触发自动化工具调用链</li> </ul> </li> </ul> 七、运行 Demo</a> </h2> 7.1 标准输入输出模式</a> </h3> python llamaindex_mcp_example.py --client_type stdio </code></pre> 执行输出示例</a> </h3> [DEBUG] 检测到ListToolsRequest协议请求 [工具调用] 步骤ID: ede14770-91c9-428b... | 输入: 我的IP所在城市是哪里？ [推理日志] 当前用户语言：中文，需调用工具获取数据 [动作触发] fetch_ipinfo | 参数: {} [网络请求] 调用MCP工具耗时128ms [观察结果] {"ip": "183.193.123.192", "city": "上海", "country": "CN"...} [最终响应] 您的IP所在城市为上海 [法律咨询] 步骤ID: e728f5d0-6c0e-454a... | 输入: 持有大麻是否合法？ [推理日志] 已确认用户所在国家：中国 [知识库检索] 加载中国刑法第357条 [最终响应] 根据中国法律，持有大麻属违法行为，最高可判处有期徒刑 </code></pre> 7.2 SSE 服务模式</a> </h3> # 终端1：启动SSE服务端 python mcp_server.py --server_type sse # 终端2：运行客户端 python llamaindex_mcp_example.py --client_type sse </code></pre> 八、技术方案总结</a> </h2> 通过以下三步实现深度集成： 协议通信层</a> </h3> 基于 MCPClient 实现服务发现与工具调用</li> 支持 SSE/STDIO 双模连接，适应不同部署场景</li> </ul> 类型转换层</a> </h3> 动态将 JSON Schema 转换为 Pydantic 模型</li> 实现参数自动校验与类型提示</li> </ul> def create_dynamic_model(schema): # 自动生成带字段描述的Pydantic模型 fields = { name: (map_type(prop), Field(..., description=prop["description"])) for name, prop in schema["properties"].items() } return create_model("DynamicModel", **fields) </code></pre> 智能代理层</a> </h3> 集成 ReAct 推理框架实现自动化工具调度</li> 通过系统提示词约束工具使用规范</li> </ul> SYSTEM_PROMPT = """\ 法律咨询必须遵循以下规则： 1. 首次响应前必须调用fetch_ipinfo确认用户辖区 2. 引用法律条文需标注具体条款编号 3. 不得对未覆盖地区提供法律建议""" </code></pre> 通过持续扩展 MCP 生态，开发者可快速构建具备专业领域能力的智能代理系统。欢迎访问 MCP 开发者社区获取更多工具资源。 查看源代码：https://github.com/psiace/psiac VLM 解析非结构化图像：一个极简可扩展方案 2024-11-28T00:00:00+00:00 这篇文章展示一种非常直接的做法：用 VLM（Visual Language Models）解析图片中的非结构化信息。 它足够简单，但也保留了明确的扩展路径，比如继续支持 PDF、表格、视频帧等更复杂场景。 如果你想要一条更重型的工业化路线，可以看 LlamaParse</a> 这类产品，它会叠加 OCR、表格解析等更多步骤。 我们先看一个常见场景：你有一批图片，需要抽取文字；或者你想给图片生成可检索描述，用于全文搜索。 这类事情，正适合交给 VLM。 我示例里用的是 llama_index</a>，但核心思路和具体框架无关，迁移到你自己的客户端也很容易。 先上代码</a> </h2> 第一步是定义一个明确的提示词，让模型知道输出结构和覆盖范围。 BASIC_PROMPT = """ Please analyze this image comprehensively and provide the following information: 1. General Overview: - Main subject matter and content - Overall composition and context - Key visual elements present 2. Text Content: - Transcribe any visible text accurately - Include headers, labels, and captions - Note any important text formatting or emphasis 3. Data Visualization (if present): - For tables: * Convert to markdown format * Preserve column headers and data relationships - For charts/graphs: * Describe the type of visualization * Explain key trends and patterns * List important data points and values - For diagrams/flowcharts: * Explain the structure and relationships * Describe the flow or process * Note any important symbols or annotations 4. Additional Details: - Identify any branding or logos - Note color schemes if significant - Describe any relevant metadata or context Please format the response clearly and maintain the original structure of any data. """ </code></pre> 接下来是一个最小可运行的图片解析器： from pathlib import Path from typing import List import base64 from io import BytesIO from PIL import Image from llama_index.core.multi_modal_llms import MultiModalLLM from llama_index.core.multi_modal_llms.generic_utils import ImageDocument class SimpleImageParser: def __init__(self, model: MultiModalLLM): self.model = model self.prompt = BASIC_PROMPT """A simple parser for extracting information from images using VLMs. Args: model (MultiModalLLM): The multi-modal language model to use for parsing """ def process_image(self, image_path: str) -> str: """Convert image to base64 encoding""" image = Image.open(image_path) buffered = BytesIO() image.save(buffered, format="PNG") return base64.b64encode(buffered.getvalue()).decode("utf-8") async def parse(self, image_path: str) -> str: """Parse image content""" image_data = self.process_image(image_path) image_doc = ImageDocument( image_url=f"data:image/jpeg;base64,{image_data}" ) response = await self.model.acomplete( prompt=self.prompt, image_documents=[image_doc] ) return str(response) </code></pre> 核心只有两步： 把图片转成 base64。</li> 作为 image_documents</code> 传给 VLM。</li> </ol> 跑一圈</a> </h2> 下面是如何使用这个解析器： import asyncio import os import argparse from pathlib import Path from llama_index.multi_modal_llms.openai import OpenAIMultiModal from dotenv import load_dotenv load_dotenv() async def main(): parser = argparse.ArgumentParser(description="Parse image content") parser.add_argument("image_path", type=str, help="Path to the image file") args = parser.parse_args() image_path = Path(args.image_path) if not image_path.exists(): print(f"Image file does not exist: {image_path}") return # Initialize the VLM model = OpenAIMultiModal( model=os.getenv("MULTI_MODAL_LLM_MODEL", "gpt-4o-mini"), api_key=os.getenv("MULTI_MODAL_LLM_API_KEY"), api_base=os.getenv("MULTI_MODAL_LLM_API_BASE", "https://api.openai.com/v1"), max_new_tokens=int(os.getenv("MULTI_MODAL_LLM_MAX_TOKENS", "512")), temperature=float(os.getenv("MULTI_MODAL_LLM_TEMPERATURE", "0.7")), verbose=os.getenv("MULTI_MODAL_LLM_VERBOSE", "False").lower() == "true", ) # Create parser and parse image parser = SimpleImageParser(model) result = await parser.parse(str(image_path)) print(result) if __name__ == "__main__": asyncio.run(main()) </code></pre> 这段代码会初始化 VLM，创建解析器，然后输出解析结果。 运行 Demo</a> </h2> 完整示例代码在这里： psiace/demo/vlm-parsing</a></li> </ul> 运行方式： python basic.py <image_path> </code></pre> 示例图片是一张家庭网关界面截图（来源：Home gateway example</a>）： 终端中的解析输出示例： Bonus：如何扩展这个 Parser</a> </h2> 下面是几个实用扩展方向： 格式支持</li> </ol> 用 pdf2image</code> 处理 PDF。</li> 用 opencv-python</code> 抽取视频帧后再解析。</li> </ul> 输出形态</li> </ol> 增加 JSON 输出：</li> </ul> async def parse_to_json(self, image_path: str) -> dict: result = await self.parse(image_path) # Add your JSON transformation logic here return json_result </code></pre> 用 Jinja2 等模板工具生成更稳定的结构化文本。</li> </ul> 处理流水线</li> </ol> 接入 Tesseract OCR 做文字前处理。</li> 追加表格解析能力。</li> 用 asyncio 做批处理。</li> </ul> 系统集成</li> </ol> 接入 llama-index 做 RAG。</li> 进一步封装成自动化工作流。</li> </ul> Resources</a> </h2> llama-index Documentation</a></li> OpenAI</a></li> PIL (Python Imaging Library)</a></li> </ul> 如果你只想快速验证“VLM 解析图片”是否有业务价值，这个极简方案足够开始。 先跑通最小闭环，再决定是否引入 OCR、表格结构化和更复杂的工程管线。 别急着招 DevRel 2024-03-08T00:00:00+00:00 先别打广告牌</a> </h2> 很多团队把 DevRel 想成会写文案、会上台、能在社交媒体刷存在感的“吉祥物”。真要这样，不如直接买块广告牌，或者训练一只会说话的鹦鹉。DevRel 如果只是扩音器，迟早会在会议室里被当成背景音。 真正的 DevRel 是把产品和开发者社区连接起来的桥。从用户视角出发，帮团队把复杂的技术语言翻译成可理解、可落地的解决方案。他既要懂产品路线，也要摸得清社区脉搏；既能撸代码，也能写故事。 三件事想清楚</a> </h2> 1. 权责资源要匹配</a> </h3> DevRel 需要参与决策，至少要能影响产品优先级和内容走向。如果每次都被挡在“等业务拍板”之外，他说的任何话都会显得苍白。给予授权，也意味着给足资源：真实数据、工程背景、核心成员的时间。 2. 叙事要一致</a> </h3> 让 DevRel 深入团队，把一线的设计取舍、踩坑记录都吸纳进来。只有这样，他们写出来的内容才像亲历者——不是新闻稿，也不是照本宣科的教程，而是能回答“为什么值得一试”这样的疑问。 3. 诚恳比形式更难</a> </h3> 社区对虚假的热情特别敏感。与其用堆砌的 buzzword，不如老老实实讲“我们是怎么解决 X 问题的”“我们做错过什么”。真诚是唯一的复利策略。 什么时候暂缓</a> </h2> 如果你还没准备好让 DevRel 拿到这些权力与资源，那就别急着招人。让创始人或者资深工程师先上阵：他们说话更有分量，也更容易获得团队信任。真正需要 DevRel 的时刻，是你想把这套叙事机制变成常态的时候。 DevRel 永远不是灵丹妙药。它是一种长期投入，需要团队，把“讲清楚”和“做得好”同时放在心上。 A New Beginning, with Astro 2023-09-25T00:00:00+00:00 中文翻译正在整理，以下为英文原文。 </blockquote> Hey, World!</a> </h2> I am delighted to announce the launch of my new blog, which is powered by Astro</a> and features the Astro Cactus</a> theme. In this fresh start, I have cleared all previous content to create a clean slate. Why and Why Not?</a> </h2> The idea of starting anew had been on my mind for a few months, but it was my recent conversation with @Xuanwo</a> that finally pushed me to take action. There are numerous reasons behind this decision: I aspire to connect with a broader audience and have a more significant impact. </blockquote> I aim to express my insights more effectively, moving beyond mere documentation of events. </blockquote> However, in reality, the decision was not driven by extensive contemplation; it was simply a matter of “Why not?” Striving to do my best is sufficient. I hope you’ll join me on this exciting journey!

尚卓燃 · PsiACE - 文章

木匠，锤子，钉子

即时通讯与社会化评估

被缚的普罗米修斯

重新发明打孔纸带

我的 2025：All in DB 的第五年

聊聊测试自信

Live a Little · 下篇（2021 – 2025）

Agent Client Protocol Python SDK 的新篇章

Live a Little · 上篇（2016 – 2021）

用 Spec 做 SDK - 生成式 AI 的时代

ACP：交互契约与 Python SDK

与其他标准的关系</a> </h2> AG-UI</strong>：同样关注交互层，部分语义重合，可能会出现“互转/共存”的场景。</li> MCP</strong>：负责工具和资源接入，适合与 ACP 搭配使用（工具能力来自 MCP，交互流程由 ACP 承载）。</li>

Zed 的视角</a> </h2> 使用者：可以把 Claude Code、Gemini CLI、内部 Agent 统统接进编辑器，享受一致的流式体验和工具栏。</li> 开发者：写一次 ACP，就能跑在任何支持它的宿主上，减少重复 glue code。</li>

Agent 没有秘密可言

TL;DR</a> </h2> Agent 不是新宗教</strong>。它依然是事件、队列、CRUD 的工程实践，再加一层模型协作。</li> 共用一条 EventBus，把 agent.*</code> 与 huey.*</code> 事件打通；每条事件立即打印；最后用 Cascade 树复盘因果与时间。</li>

为什么写这个（以及为什么这么写）</a> </h2> 我不想再讨论"如何画出一个复杂的 Agent 架构图"。我更关心"如何让系统解释得清楚、失败得优雅、复盘得明白</strong>"。</li>

事件流（概览）</a> </h3> </p> 这和"传统架构"有什么不同？</a> </h2> 没有不同</strong>：事件、队列、CRUD，本来就在；只是把模型作为协作者接了进来。</li>

这和"传统架构"有什么不同？</a> </h2> 没有不同</strong>：事件、队列、CRUD，本来就在；只是把模型作为协作者接了进来。</li>

如何运行（单终端）</a> </h2> 代码位置</a> </h3> 请点击【阅读原文】跳转：</p> agent_has_no_secret.py</a></li> README.md</a></li> </ul> 运行步骤</a> </h3> 配置 .env</code>（OpenRouter 推荐；OpenAI 也可）</li>

代码位置</a> </h3> 请点击【阅读原文】跳转：</p> agent_has_no_secret.py</a></li> README.md</a></li> </ul> 运行步骤</a> </h3> 配置 .env</code>（OpenRouter 推荐；OpenAI 也可）</li>

运行步骤</a> </h3> 配置 .env</code>（OpenRouter 推荐；OpenAI 也可）</li>

你将看到什么</a> </h3> 实时事件流</strong>：user.input</code>、agent.thought</code>、agent.action</code>、huey.data.*</code>、agent.observation</code> …</li> 绿色的 Final Answer</strong> 面板</li>

Baby Steps: 用 Python 实现一个能自举的 Coding Agent

让 LlamaIndex 接上 Cloudflare AI Gateway

为什么折腾这个</a> </h2> 单供应商的 LLM 太脆弱：OpenAI 宕机、Anthropic 限流，就等于业务停摆。Cloudflare AI Gateway 给了一个诱人的承诺：</p> 多家模型的统一入口；</li> 内置缓存、限流、熔断；</li>

能做什么</a> </h2> 顺序尝试多个模型，失败自动换下一个；</li> 支持 Cloudflare 的流式接口、异步调用；</li> 统一注入鉴权、重试、日志；</li> 经过实测的模型：OpenAI、Anthropic；</li>

用 WebAssembly 为 Code Agent 范式构建安全沙箱

当 RAG 遇上编程助手

想试试的话，从简单开始</a> </h2> 如果你也想写个编程助手，但不想搞得太复杂，可以这样开始：</p> </p> 先写一些规则和提示词</li> 用简单的搜索工具找文档</li> 写个脚本查 StackOverflow</li>

RAG 没有捷径

NebulaGraph MCP Server 正式开源！探索 AI+图数据库无限可能

把 MCP 工具塞进 LlamaIndex 工作流

关键技术创新点</a> </h3> 动态模式转换：实现 JSON Schema 到 Pydantic 模型的运行时转换，保证参数校验的严格性</li> 异步调用管道：基于 Python asyncio 构建非阻塞式服务调用，提升工具执行效率</li>

你将看到什么 </a> </h3>
`写在最后</a> </h2> 我更钦佩能把东西"说清楚、跑起来</strong>"的工程师。Agent 没有秘密可言：</p> 先把闭环打通，再考虑花活；</li> 先让因果与代价可见，再谈"更聪明"。</li> </ul>`

关键技术创新点 </a> </h3>
关键实现解析 </a> </h3>

工具获取机制：
智能代理配置：
消息处理流程：