构建流式本地AI代理
内容提要
本文介绍如何构建一个始终在线的流式AI代理，用于监控维基百科实时编辑流并检测恶意编辑。系统采用两阶段漏斗设计：第一阶段用廉价Python逻辑过滤大多数无关编辑，第二阶段仅对可疑事件调用本地LLM（通过Ollama）进行深度分析。代理支持实时流式输出推理过程，并通过SSE广播给客户端。文章强调效率、自动重连和优雅降级对始终在线系统的重要性。
延伸解读
两阶段漏斗：成本与延迟的关键
文章强调，始终在线的流式代理必须处理高吞吐事件流，若将所有事件直接交给LLM，会消耗大量计算资源并导致代理落后于实时流。因此，采用两阶段漏斗设计：第一阶段用廉价Python逻辑过滤大多数无关事件，第二阶段仅对可疑事件调用本地LLM。这种设计遵循监控系统的基本原则：廉价过滤在前，昂贵推理在后，是保证系统可持续运行的核心。
流式输出的双重含义
本文区分了“流式”的两种含义：一是代理消费实时事件流，二是代理输出逐token流式生成。作者指出，大多数教程只实现其中一种，而真正有用的始终在线代理需要同时解决这两个问题。本文构建的系统通过SSE广播实时推理过程，让客户端能观察模型思考过程，同时保持结构化输出，兼顾实时性和可用性。
优雅降级与自动重连
始终在线的系统必须处理网络中断、慢客户端和模型错误。本文通过自动重连机制应对连接断开，通过有界队列和丢弃策略防止慢客户端阻塞处理循环，并在Stage 2异常时记录错误并继续处理下一事件。这些设计确保系统在长时间运行中保持稳定，避免因单点故障而失效。
Q&A
如何构建一个流式本地AI代理来监控维基百科的实时编辑？
构建一个流式本地AI代理需要结合实时事件流消费、两阶段漏斗过滤和本地LLM推理。具体步骤包括：使用Python消费维基百科的EventStreams（SSE），用廉价规则过滤大部分无关编辑，仅对可疑事件调用本地Ollama模型进行深度分析，并通过SSE将推理过程实时广播给客户端。
为什么在流式AI代理中要使用两阶段漏斗设计？
因为维基百科的编辑流每秒产生多条编辑，如果全部交给LLM处理，会消耗大量计算资源且导致代理跟不上实时流。两阶段漏斗先用廉价的Python逻辑（如删除字节数、编辑频率）过滤掉大多数无关编辑，只对少数可疑事件调用LLM，从而保证效率和实时性。
如何检测维基百科编辑流中的匿名用户？
维基百科的EventStreams没有显式的匿名标志，匿名编辑的用户名是IP地址。因此通过检查用户名是否符合IPv4或IPv6地址格式来识别匿名用户。
如何确保流式AI代理在断线时能自动重连？
在消费维基百科事件流的函数中，使用while True循环包裹连接逻辑，并在捕获到HTTP错误时等待5秒后重试，从而确保代理在断线后能自动恢复连接，保持始终在线。
如何让本地LLM输出结构化JSON结果？
使用Ollama的format参数，传入Pydantic模型（如AgentVerdict）的JSON Schema，这样Ollama在生成时就会强制输出符合该Schema的JSON，保证输出可直接解析为结构化对象。
如何将AI代理的推理过程实时流式传输给客户端？
通过Broadcaster类实现发布-订阅模式，每个客户端订阅一个asyncio.Queue，代理在生成token时通过publish方法将消息推送到所有订阅队列，客户端通过SSE端点（/events）接收这些消息，实现实时流式输出。
构建流式本地AI代理需要哪些前提条件？
需要Python 3.11或更高版本，本地安装Ollama并拉取支持结构化输出的模型（如llama3.1:8b），以及安装fastapi、uvicorn、httpx、pydantic、ollama、sse-starlette等Python包。无需API密钥或云账户。
如何运行这个流式本地AI代理？
首先确保Ollama已安装并运行，然后创建虚拟环境并安装依赖，最后使用uvicorn启动FastAPI应用。启动后，可以通过curl或浏览器访问http://localhost:8000/events来查看实时流。
