转写说明

本文基于已校验的公开原文进行结构化转写与事实梳理，非原文转载。 转写保留可核验的技术事实，并将工程建议与来源观点明确分开。

核心结论

Agent 项目真正的难点不在能否跑通 demo，而在四个维度：效果可评估、成本可控制、出错可追溯、风险可管控。实践中分别对应 RAG 阈值兜底与引用溯源、迭代上限与 Token 统计、全链路 Trace 落盘、四层护栏与人工介入（HITL）。

能力机制

工程与环境适配

Python 3.6 与现代 AI 库存在兼容性问题，建议通过独立虚拟环境使用更高版本 Python。创建虚拟环境后安装依赖时，应先清空 PYTHONPATH 环境变量，避免继承 IDE 注入的 sitecustomize.py 导致 shutil.move 报错。

dataclass 字段使用可变默认值（如空列表）会触发 ValueError，正确做法是使用 field(default_factory=…) 声明。FastAPI 的 on_event(“startup”) 已废弃，需改用 lifespan 异步上下文管理器实现启动逻辑。Maven 在 BOM 模式下仅配置 java.version 不生效，必须显式指定 maven.compiler.release。

Agent 编排要点

LangGraph 的 invoke 方法为同步调用，在异步服务中直接调用会阻塞事件循环。解决方案是通过线程池执行工作流，并使用 loop.call_soon_threadsafe 回传事件。早期版本缺少迭代上限控制，当工具持续返回空结果时会导致 Agent 无限重试消耗 token，建议设置三层限制：MAX_ITERATIONS=6、Reflect 最多补 2 步、Plan 最多 3 步。

RAG 检索改进

纯哈希向量对中文短句区分度不足，推荐采用中文单字与相邻双字（bigram）结合作为 token，叠加 BM25 关键词召回，使用 RRF 融合两种召回结果。当检索置信度低于阈值时应直接返回空结果，避免模型硬编导致幻觉，这是最常见的幻觉来源。按字数硬切文本会把关联条款拆分到不同 chunk，应优先按 Markdown 标题结构切块，超长内容再递归按句子切分。

安全护栏

Text2SQL 场景中字段名错误会导致查询永久失败，需将数据库错误信息拼入 prompt 触发重生成，一次修正成功率会明显提升。多语句注入（分号后跟额外语句）必须拦截，检测到分号后存在后续内容应直接拒绝。eval 实现计算器必须采用 AST 白名单方式，仅允许数字常量、四则运算与幂运算。

前端 SSE 处理

EventSource 原生不支持 POST 请求，需改用 fetch 配合 ReadableStream 手动解析 SSE。中文文本可能被 TCP 分包截断，decoder.decode 必须添加 stream: true 参数，并将未完整部分保留在 buffer 中待下次拼接。后端线程池执行的事件通过 call_soon_threadsafe 回传，顺序由队列保证不会乱序。

快速开始

1
2

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

初始化虚拟环境后，启动前清空可能干扰的环境变量。

dataclass 定义需使用正确语法：

1
2
3
4

from dataclasses import field
from typing import List

spans: List[Span] = field(default_factory=list)

FastAPI 应用启动逻辑写法：

1
2
3
4
5
6
7
8
9

from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    _startup()
    yield

app = FastAPI(lifes踪=lifespan)

异步服务中调用同步 LangGraph 工作流时：

1
2

def sink(event): loop.call_soon_threadsafe(queue.put_nowait, event)
asyncio.get_running_loop().run_in_executor(None, worker)

适用边界

本文档适用于已具备基础开发能力、需要将 AI Agent 项目落地生产的工程团队。涉及的框架包括 Python 虚拟环境管理、LangGraph 编排层、FastAPI 服务层、RAG 检索链路、Text2SQL 工具调用，以及前端 SSE 通信。

文档覆盖了从环境配置、Agent 核心逻辑、检索增强、安全防护到前端交互的完整链路问题。对于仍在探索阶段的 PoC 项目，部分优化项（如迭代上限、Token 统计、Trace 落盘）可按需引入；对于已上线或即将上线的项目，四层安全护栏与效果可评估机制应优先落地。

文档未涵盖的内容包括：模型选型对比、非 Python 技术栈的 Agent 实现、纯向量数据库运维细节、前端框架特定集成方案。这些方向需要结合具体业务场景与团队技术栈另行评估。

核验清单

环境与依赖

  • 虚拟环境隔离检查：已创建独立 venv，未污染系统 Python
  • PYTHONPATH 清理：安装依赖前已执行清空操作
  • dataclass 声明：所有可变类型字段均使用 default_factory

Agent 编排

  • 异步调用链路：同步 invoke 已通过线程池隔离，未阻塞事件循环
  • 迭代保护：MAX_ITERATIONS、Reflect 步数、Plan 步数三层限制已配置
  • JSON 解析：输出解析器具备去代码块、截取内容块、兜底返回三容错能力
  • 中间事件捕获：测试代码传入 sink 回调接收非最终输出

RAG 链路

  • 中文分词：已采用字级别与 bigram 结合的 token 策略
  • 多路召回：BM25 与向量召回已融合，结果使用 RRF 合并
  • 阈值兜底：置信度低于设定值时返回空结果而非硬编
  • 文本切分：优先按 Markdown 标题结构切块，递归处理超长块

安全护栏

  • SQL 错误闭环：数据库错误信息已回传 prompt 触发重生成
  • 注入拦截：多语句检测已实现，分号后存在内容直接拒绝
  • 危险函数：eval 已替换为 AST 白名单计算器

前端通信

  • SSE 实现：fetch + ReadableStream 方案已替代 EventSource
  • 分包处理：decoder 配置 stream: true，buffer 保留不完整尾串
  • 事件顺序：后端使用 call_soon_threadsafe 回传，队列保证顺序

来源与核验

  • 原始文章
  • 页面事实以原始来源及其引用的官方资料为准；版本、星标和模型能力会随时间变化。
  • AI Stack 不公开抓取到的全文快照，只发布独立转写与来源入口。

站内链接

相关文章