知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# ReAct 模块工程设计指南 > 导读:本文从"ReAct 的 demo 一天就能跑通,为什么上线后天天出格式解析错误、死循环和 Context 超限"这个最真实的痛点出发,把 ReAct 的 Prompt 设计、多层输出解析、工具注册与安全调度、完整 Agent 组装、变体选型与生产可观测性逐项讲透,最后给出配置参数与四类高频故障的排查手册。适合已经理解 ReAct 原理、正准备把它推进生产环境的同学。 ## 一、先建立全局认知 ### Q:ReAct 的 Demo 和 ReAct 的生产版本,差距到底在哪? A:结论先行——**差距不在"循环本身",而在循环周边的三件事:输出格式的容错解析、工具执行的安全与超时边界、以及可观测与配置兜底**。Demo 里 LLM 输出格式规范、工具永远返回成功、上下文永远不超限;生产里这三条假设全部不成立。 具体看,生产环境会打破 Demo 的哪些假设: | Demo 假设 | 生产的现实 | 对应工程模块 | |---|---|---| | 模型老实按"思考/行动/参数"输出 | 小模型经常跑格式、加 Markdown、少字段 | 多层输出解析器 + 解析失败重试 | | 工具名和参数一定正确 | 工具名幻觉、参数类型错、JSON 语法错 | 工具注册表 + Schema 校验 | | 工具调用快且稳定 | 超时、限流、慢查询、异常 | 超时控制 + 安全执行包装层 | | 轮次不多 | 死循环、反复调用同一工具 | 最大迭代 + 单工具调用上限 | | 上下文够用 | 工具返回长文本导致 Context 超限 | 输出截断 + 摘要 | 所以"从原理到生产级实现"要补的就是这张表的右列。**换句话讲,ReAct 原理只占工程量的三成,剩下七成全是围绕"模型不可靠"做的防御性设计。** ### Q:标准 ReAct 循环在代码里是怎么搭起来的? A:结论先行——**它就是一个 `while iteration < max_iterations` 的循环,每轮做四件事:调 LLM → 解析输出 → 若是工具调用则执行并把 Observation 追加到消息历史 → 若是最终答案则返回**。  *图:ReAct 工程实现的完整循环——推理、解析、分支与回边* ```text ┌───────────────────────────────┐ │ 构建初始消息(system+user) │ └───────────────┬───────────────┘ ▼ ┌───────────────────────────────┐ │ 循环开始(iteration < max) │ │ 1. LLM 推理 → raw_output │ │ 2. 解析 → ReActStep │ │ 3. 分支: │ │ FINAL_ANSWER → 返回答案 │ │ THOUGHT_ACTION → 执行工具 │ │ 追加 Observation 到历史 │ │ PARSE_ERROR → 提示重写格式 │ └───────────────┬───────────────┘ │ 未完成 └──────► 回到循环开始 超出 max_iterations → 返回降级提示 ``` 三个设计要点值得提前记住: 1. **消息历史是唯一的状态载体**。每执行一次工具,就把"模型刚才的原文"作为 assistant 消息、"观察:xxx"作为 user 消息追加进去。模型下一轮看到的完整上下文,就是它能"记住自己做过什么"的全部依据。 2. **必须有无条件退出路径**。`max_iterations` 不是优化项,是安全阀;没有它,一个格式持续解析失败的模型会让循环一直跑下去。 3. **解析失败不是异常,是一种正常分支**。它要能被识别、被记录、并能引导模型自我修正,而不是直接抛错中断。  *图:ReAct 执行循环* ### Q:ReAct 的 System Prompt 应该怎么写才稳? A:结论先行——**Prompt 必须精确定义输出格式(思考/行动/参数 与 思考/最终答案 两种形态)、可用工具列表、以及若干行为约束(每次只调一个工具、不许假设工具结果、失败要换方法、有最大步数),让模型的输出是可被程序解析的"半结构化协议"**。 ```python REACT_SYSTEM_PROMPT = """你是一个智能助手,通过思考和使用工具来回答问题。 ## 可用工具 {tools} ## 输出格式 每一步必须严格按照以下格式输出,不要有多余内容: 思考:[你的推理过程,分析当前情况和下一步应该做什么] 行动:工具名称 参数:{{"参数名": "参数值"}} 或者,当你有足够信息可以直接回答时: 思考:[分析已有信息,确认可以回答] 最终答案:[直接给出完整答案] ## 重要规则 1. 每次只能执行一个工具 2. 工具结果(观察)会在下一轮提供给你 3. 不要假设工具结果,必须等待实际观察 4. 如果工具调用失败,分析原因并尝试其他方法 5. 最多执行 {max_iterations} 步,超出后直接给出最佳答案 """ ``` **逐条解读每条规则背后的工程动机**: - `{tools}` 占位符注入的是工具注册表动态生成的描述,**保证 Prompt 里的工具清单与代码里注册的工具永远一致**,避免手工维护两份清单而漂移。 - "每次只能执行一个工具"是为了让解析器一次只需处理一个 Action——如果模型一次吐多个,解析归因会变复杂,Observation 也无法一一对应。 - "不要假设工具结果"是防幻觉的核心约束。**没有这一条,模型很容易跳过工具直接编造 Observation**。 - "最多执行 {max_iterations} 步,超出后直接给出最佳答案"是软约束,配合代码里的硬性 `max_iterations` 一起用——软约束让模型有机会主动收尾,硬约束保证系统一定能退出。 - 参数用 JSON 对象 `{{"参数名": "参数值"}}` 而非自由文本,是为了让下游能直接 `json.loads`,把"解析自然语言"降级成"解析 JSON"。 ## 二、理解核心机制 ### Q:为什么必须写一个独立的输出解析器?直接用正则取出来不行吗? A:结论先行——**不行,因为 LLM 输出不稳定是 ReAct 工程化的最大挑战,必须用"多层容错 + 启发式兜底"的解析器把不确定的文本收敛成确定的结构化步骤(ReActStep)**。单条正则只要遇到一次格式变体(中文冒号、英文标签、Markdown 包裹、JSON 语法错),整轮就崩。 解析器的设计目标是把"任意文本"映射到三种确定状态之一:  *图:ReAct 输出解析:raw_output 的三种分支结果* ```text raw_output(模型原始输出,不可预测) │ ▼ ┌───────────────────────────┐ │ ReActOutputParser.parse │ └───────────────┬───────────┘ ▼ ┌──────────────┬───────────────┬────────────────┐ │ THOUGHT_ACTION│ FINAL_ANSWER │ PARSE_ERROR │ │ 需执行工具 │ 直接返回答案 │ 提示模型重写格式 │ └──────────────┴───────────────┴────────────────┘ ``` **为什么用 dataclass + Enum 来承载结果?** 因为后续的循环只关心"步骤类型 + 字段内容",不关心原始文本。把两种输出形态(工具调用 / 最终答案)归一到一个 `ReActStep` 结构里,循环主体的分支逻辑就是干净的 `if/elif/else`,同时还能保留 `raw_output` 用于日志与排查。 ### Q:解析器的容错策略具体怎么分层? A:结论先行——**分三层:第一层按优先级尝试多套正则(中文标准格式优先,英文格式降级兼容);第二层对 JSON 参数做修复(单引号、尾随逗号);第三层启发式兜底(长文本且无工具痕迹就当最终答案,否则标 PARSE_ERROR)**。 ```python import re from dataclasses import dataclass from enum import Enum class StepType(Enum): THOUGHT_ACTION = "thought_action" FINAL_ANSWER = "final_answer" PARSE_ERROR = "parse_error" @dataclass class ReActStep: step_type: StepType thought: str = "" action: str = "" action_input: dict = None final_answer: str = "" raw_output: str = "" class ReActOutputParser: # 多种格式的正则,按优先级尝试 PATTERNS = [ # 标准格式 { "thought": r"思考[::]\s*(.+?)(?=\n行动[::]|\n最终答案[::]|$)", "action": r"行动[::]\s*(.+?)(?=\n参数[::]|\n观察[::]|$)", "action_input": r"参数[::]\s*(\{.+?\})", "final_answer": r"最终答案[::]\s*(.+?)$" }, # 英文格式(降级兼容) { "thought": r"Thought[::]\s*(.+?)(?=\nAction[::]|\nFinal Answer[::]|$)", "action": r"Action[::]\s*(.+?)(?=\nAction Input[::]|\nObservation[::]|$)", "action_input": r"Action Input[::]\s*(.+?)(?=\nObservation[::]|$)", "final_answer": r"Final Answer[::]\s*(.+?)$" } ] def parse(self, text: str) -> ReActStep: text = text.strip() for pattern_set in self.PATTERNS: result = self._try_parse(text, pattern_set) if result: return result # 所有格式都失败,做最后的启发式尝试 return self._fallback_parse(text) def _try_parse(self, text: str, patterns: dict) -> ReActStep | None: # 检查是否是最终答案 final_match = re.search(patterns["final_answer"], text, re.DOTALL | re.IGNORECASE) if final_match: thought_match = re.search(patterns["thought"], text, re.DOTALL | re.IGNORECASE) return ReActStep( step_type=StepType.FINAL_ANSWER, thought=thought_match.group(1).strip() if thought_match else "", final_answer=final_match.group(1).strip(), raw_output=text ) # 检查是否是工具调用 action_match = re.search(patterns["action"], text, re.DOTALL | re.IGNORECASE) if action_match: thought_match = re.search(patterns["thought"], text, re.DOTALL | re.IGNORECASE) input_match = re.search(patterns["action_input"], text, re.DOTALL) action_input = {} if input_match: try: import json action_input = json.loads(input_match.group(1)) except json.JSONDecodeError: # JSON 解析失败,尝试修复 action_input = self._repair_json(input_match.group(1)) return ReActStep( step_type=StepType.THOUGHT_ACTION, thought=thought_match.group(1).strip() if thought_match else "", action=action_match.group(1).strip(), action_input=action_input, raw_output=text ) return None def _fallback_parse(self, text: str) -> ReActStep: """启发式兜底解析""" # 如果文本较长且没有工具调用痕迹,当作最终答案 if len(text) > 100 and not any( kw in text for kw in ["行动", "Action", "工具", "Tool"] ): return ReActStep( step_type=StepType.FINAL_ANSWER, final_answer=text, raw_output=text ) return ReActStep( step_type=StepType.PARSE_ERROR, raw_output=text ) def _repair_json(self, text: str) -> dict: """尝试修复常见的 JSON 格式问题""" # 处理单引号 text = text.replace("'", '"') # 处理末尾逗号 text = re.sub(r',\s*}', '}', text) text = re.sub(r',\s*]', ']', text) try: import json return json.loads(text) except Exception: return {"raw": text} ``` **关键点解读**: - **先判最终答案、再判工具调用**:顺序不能反。因为最终答案的文本里可能包含"行动"字样(比如回答内容本身在讨论"行动"),若先匹配 action 就会误判。 - **`[::]` 同时匹配中英文冒号**、`re.IGNORECASE` 忽略大小写,这两个小细节能挡掉大量真实世界的格式漂移。 - **正则用非贪婪 + 前瞻(`(?=...)`)**,是为了让"思考"在遇到"行动"或"最终答案"时正确截断,而不是一路吃到文本末尾。 - **`_repair_json` 是最后的体面**:模型常输出 Python 风格的单引号字典或带尾随逗号,修复后仍能拿到参数;彻底修不好时返回 `{"raw": text}`,**至少让工具收到一个可解释的参数而不是直接抛异常**。 - **兜底启发式里"无工具痕迹即当最终答案"是经验性取舍**:它能避免模型只是忘了写"最终答案"标签时被判为解析失败;但阈值 `len(text) > 100` 是经验值,需结合你的模型输出长度分布调参。 ## 三、工具调度与安全 ### Q:工具注册表(ToolRegistry)该怎么设计?Schema 能自动生成吗? A:结论先行——**可以。用 `inspect.signature` 从函数签名自动推导 JSON Schema,把函数、描述、参数定义、返回值描述统一注册到一个字典里,再动态生成注入 Prompt 的工具描述**。这样"代码里注册了什么"和"模型看到什么"永远一致。 ```python from typing import Callable, Any from pydantic import BaseModel import inspect class ToolSchema(BaseModel): name: str description: str parameters: dict # JSON Schema returns: str # 返回值描述 class ToolRegistry: """工具注册中心""" def __init__(self): self._tools: dict[str, dict] = {} def register( self, name: str, func: Callable, description: str, returns: str = "string" ): # 自动从函数签名生成 JSON Schema schema = self._generate_schema(func) self._tools[name] = { "func": func, "schema": ToolSchema( name=name, description=description, parameters=schema, returns=returns ) } def get_tool_descriptions(self) -> str: """生成注入 Prompt 的工具描述""" descriptions = [] for name, tool in self._tools.items(): schema = tool["schema"] params = ", ".join( f"{k}({v.get('type', 'any')}): {v.get('description', '')}" for k, v in schema.parameters.get("properties", {}).items() ) descriptions.append( f"- **{name}**({params})\n {schema.description}" ) return "\n".join(descriptions) async def execute( self, tool_name: str, tool_input: dict, timeout: float = 30.0 ) -> tuple[bool, str]: """执行工具,返回 (success, result)""" if tool_name not in self._tools: return False, f"工具 '{tool_name}' 不存在,可用工具:{list(self._tools.keys())}" tool = self._tools[tool_name] func = tool["func"] try: import asyncio if inspect.iscoroutinefunction(func): result = await asyncio.wait_for(func(**tool_input), timeout=timeout) else: result = await asyncio.wait_for( asyncio.get_event_loop().run_in_executor(None, lambda: func(**tool_input)), timeout=timeout ) return True, str(result) except asyncio.TimeoutError: return False, f"工具 '{tool_name}' 执行超时({timeout}s)" except TypeError as e: return False, f"工具参数错误:{e},期望参数:{list(tool['schema'].parameters.get('properties', {}).keys())}" except Exception as e: return False, f"工具执行失败:{type(e).__name__}: {e}" def _generate_schema(self, func: Callable) -> dict: sig = inspect.signature(func) properties = {} required = [] for name, param in sig.parameters.items(): if name == "self": continue prop = {"type": "string"} if param.annotation != inspect.Parameter.empty: type_map = {str: "string", int: "integer", float: "number", bool: "boolean"} prop["type"] = type_map.get(param.annotation, "string") if param.default == inspect.Parameter.empty: required.append(name) properties[name] = prop return {"type": "object", "properties": properties, "required": required} ``` **关键点解读**: - **返回值统一成 `(success, result)` 二元组**,而不是抛异常或返回裸结果。这逼着调用方显式处理失败,也让 Observation 可以携带"失败原因"回灌给模型。 - **异步函数与同步函数要分开处理**:协程函数直接 `await`,同步函数丢到 `run_in_executor` 里跑,避免阻塞事件循环;两者都套 `asyncio.wait_for` 做超时。 - **异常分型处理**:`TimeoutError`、`TypeError`(参数错,且回传期望参数名)、其他异常各有不同的提示文案。**这正是"错误信息要有信息量"的落地——模型看到"期望参数:['city','date']"才知道怎么改。** - **工具不存在时返回可用工具清单**,给模型一次自纠机会,而不是让它继续幻觉同一个工具名。 - **类型映射表只覆盖 str/int/float/bool**,复杂类型(list、嵌套对象、枚举)会退化为 `string`。生产项目里建议直接改用显式的 Pydantic 模型或 JSON Schema,**不要依赖这种简易推导**——这是这个示例的已知边界,需结合你使用的框架版本确认行为。 ### Q:工具执行还要加哪些安全防护? A:结论先行——**至少四层:工具黑名单、单会话内调用频率上限、输入参数的危险模式校验、输出长度截断;它们分别防越权工具、防工具滥用/死循环、防注入、防 Context 爆炸**。 ```python class SafeToolExecutor: """工具执行的安全包装层""" def __init__(self, registry: ToolRegistry, config: dict = None): self.registry = registry self.config = config or {} self._call_counts: dict[str, int] = {} # 每次会话的调用次数 async def execute_safe( self, tool_name: str, tool_input: dict, session_id: str ) -> tuple[bool, str]: # 1. 工具黑名单检查 if tool_name in self.config.get("blacklist", []): return False, f"工具 '{tool_name}' 已被禁用" # 2. 调用频率限制(防止工具滥用) call_key = f"{session_id}:{tool_name}" self._call_counts[call_key] = self._call_counts.get(call_key, 0) + 1 max_calls = self.config.get("max_calls_per_tool", 10) if self._call_counts[call_key] > max_calls: return False, f"工具 '{tool_name}' 在本次会话中调用次数超限({max_calls}次)" # 3. 输入参数校验(防止注入) if not self._validate_input(tool_input): return False, "工具参数包含不允许的内容" # 4. 执行工具 success, result = await self.registry.execute(tool_name, tool_input) # 5. 输出长度截断(防止 context 爆炸) max_output = self.config.get("max_output_length", 2000) if len(result) > max_output: result = result[:max_output] + f"\n...[输出过长,已截断,完整长度 {len(result)} 字符]" return success, result def _validate_input(self, tool_input: dict) -> bool: """基础的输入安全检查""" dangerous_patterns = ["rm -rf", "DROP TABLE", "__import__", "eval("] for value in tool_input.values(): if any(pattern in str(value) for pattern in dangerous_patterns): return False return True ``` **为什么把安全做成"包装层"而不是塞进 ToolRegistry?** 因为两者的变化频率不同:工具注册是功能维度,安全策略是运维/风控维度。分层之后,安全规则可以按环境(测试/生产)、按租户独立配置,而不必改工具本身。 需要注意的边界与取舍: - **黑名单模式天然是滞后的**——只能挡已知危险项,正确姿势是"白名单 + 最小权限",让工具本身就只拥有它必需的能力。 - **`_validate_input` 的关键字匹配是很弱的防线**,字符串拼接、编码变形都能绕过,**它只能当最后一道提醒,不能当唯一防线**。真正的隔离要在执行环境层面做(沙箱、只读库账号、命令白名单)。 - **调用次数计数放在进程内存里**,多实例部署时每个实例各算各的,**要精确限流需要挪到 Redis 之类的共享存储**。 - **输出截断是必须的**,否则一次"把整张表 select 出来"就能把 Context 顶爆。但截断会丢失尾部信息,**更好的做法是工具内部先做摘要再返回**,截断只作为兜底。 ## 四、完整实现与变体选型 ### Q:把上面这些拼起来,生产级 ReActAgent 长什么样? A:结论先行——**它的 `run` 方法就是"构建初始消息 → 循环推理 → 解析 → 分支执行 → 记录步骤",并且每一步都往 `steps` 里追加一条结构化记录,最后返回包含答案、完整推理链、成功标志和执行轮次的结果对象**。 ```python from typing import AsyncIterator class ReActAgent: """生产级 ReAct Agent""" def __init__( self, llm, tool_registry: ToolRegistry, max_iterations: int = 10, memory=None, stream: bool = False ): self.llm = llm self.tools = tool_registry self.parser = ReActOutputParser() self.executor = SafeToolExecutor(tool_registry) self.max_iterations = max_iterations self.memory = memory self.stream = stream async def run( self, user_input: str, session_id: str = "default" ) -> dict: """ 返回: { "answer": str, "steps": list[dict], # 完整推理链 "success": bool, "iterations": int } """ messages = self._build_initial_messages(user_input, session_id) steps = [] iteration = 0 while iteration < self.max_iterations: iteration += 1 # LLM 推理 response = await self.llm.ainvoke(messages) raw_output = response.content # 解析输出 step = self.parser.parse(raw_output) step_record = { "iteration": iteration, "type": step.step_type.value, "thought": step.thought, "raw": raw_output } if step.step_type == StepType.FINAL_ANSWER: step_record["answer"] = step.final_answer steps.append(step_record) return { "answer": step.final_answer, "steps": steps, "success": True, "iterations": iteration } elif step.step_type == StepType.THOUGHT_ACTION: # 执行工具 success, observation = await self.executor.execute_safe( step.action, step.action_input or {}, session_id ) step_record.update({ "action": step.action, "action_input": step.action_input, "observation": observation, "tool_success": success }) steps.append(step_record) # 将工具结果追加到消息历史 messages.append({"role": "assistant", "content": raw_output}) messages.append({ "role": "user", "content": f"观察:{observation}" }) else: # 解析错误:提示 LLM 修正格式 step_record["error"] = "输出格式解析失败" steps.append(step_record) messages.append({"role": "assistant", "content": raw_output}) messages.append({ "role": "user", "content": "你的输出格式不正确,请严格按照规定格式重新输出(思考/行动/参数 或 思考/最终答案)" }) # 超过最大迭代次数 return { "answer": "抱歉,我在规定步数内未能完成任务,请尝试简化问题。", "steps": steps, "success": False, "iterations": iteration } def _build_initial_messages(self, user_input: str, session_id: str) -> list[dict]: tool_descriptions = self.tools.get_tool_descriptions() system_content = REACT_SYSTEM_PROMPT.format( tools=tool_descriptions, max_iterations=self.max_iterations ) # 注入长期记忆(如有) if self.memory: memories = self.memory.retrieve_sync(user_input, session_id) if memories: system_content += f"\n\n## 关于用户的已知信息\n{memories}" return [ {"role": "system", "content": system_content}, {"role": "user", "content": user_input} ] ``` **为什么返回 `steps` 而不是只返回 `answer`?** 这是生产与 Demo 最重要的差别之一:**完整推理链是可观测性和评测的原料**。有了它,你才能回答"这次为什么答错"(哪一步选错工具)、"平均走了几轮"(效率)、"工具失败率多高"(稳定性)。只返回答案的 Agent 在线上是不可维护的。 另外两个细节: - **`session_id` 一路传到 `execute_safe`**,让安全层的调用计数能按会话隔离,避免不同用户互相"用完额度"。 - **降级答案不是空字符串**,而是一句明确告知用户"我失败了,请简化问题"的文案。**静默失败比显式失败伤害更大**,因为它会让用户以为任务已完成。 ### Q:标准 ReAct 有哪些变体?该怎么选? A:结论先行——**变体都是围绕"补哪块短板"演化的:补个性化就加 Memory,补准确性就加 Critic,补自我改进就加 Reflexion,补复杂任务结构就加 Plan-then-ReAct,补专业分工就上 Multi-Agent**。 ```text 变体 核心差异 优势 适用场景 标准 ReAct 交替思考行动 简单,通用 大多数场景 ReAct + Memory 带长期记忆 个性化 持久对话助手 ReAct + Critic 额外验证步骤 准确率高 高精度需求 Reflexion 任务后反思 自我改进 迭代型任务 Plan-then-ReAct 先规划后执行 复杂任务结构 多步骤工程任务 Multi-Agent 多 Agent 协作 专业分工 大型复杂系统 ``` **选型的基本原则是从左往右"按需加",而不是一上来就堆最复杂的**。每加一个变体都会引入额外 LLM 调用(Critic 要一次、Reflexion 要一次、Planner 要一次),延迟和成本相应上升;只有当标准 ReAct 在某个具体指标上确实不达标时,才针对性补对应的短板。 ### Q:Reflexion(反思)增强版怎么落到代码里? A:结论先行——**用一个外层重试循环包住标准的 `run`:失败后让 LLM 基于"任务 + 执行轨迹"生成一段自然语言反思,把这段反思注入下一次尝试的输入,并把反思写进长期记忆供以后复用**。 ```python class ReActWithReflection(ReActAgent): """带自我反思的 ReAct:任务失败后自动反思并重试""" async def run_with_reflection( self, user_input: str, session_id: str, max_reflections: int = 2 ) -> dict: reflections = [] for attempt in range(max_reflections + 1): # 将历史反思注入 Prompt if reflections: enhanced_input = ( f"{user_input}\n\n" f"[注意:之前的尝试失败了,反思如下:\n" + "\n".join(f"{i+1}. {r}" for i, r in enumerate(reflections)) + "\n请避免重复相同的错误]" ) else: enhanced_input = user_input result = await self.run(enhanced_input, session_id) if result["success"]: result["reflections"] = reflections result["attempts"] = attempt + 1 return result # 任务失败,生成反思 if attempt < max_reflections: reflection = await self._reflect(user_input, result["steps"]) reflections.append(reflection) # 将反思存入记忆(如有) if self.memory: await self.memory.store( content=f"任务失败反思:{reflection}", category="error_pattern", session_id=session_id ) return {**result, "reflections": reflections, "attempts": max_reflections + 1} async def _reflect(self, original_task: str, steps: list[dict]) -> str: steps_summary = "\n".join( f"步骤{s['iteration']}: {s.get('action', '最终回答')} " f"{'成功' if s.get('tool_success', True) else '失败'}" for s in steps ) prompt = f"""你刚才尝试完成以下任务但失败了: 任务:{original_task} 执行过程: {steps_summary} 请简洁地分析失败原因,并说明下次应该怎么改进(1-3句话):""" response = await self.llm.ainvoke([{"role": "user", "content": prompt}]) return response.content ``` **关键点解读**: - **反思的输入是"轨迹"而非"结果"**——`_reflect` 吃的是 `steps` 摘要(每步的动作与成功与否),这样模型才能定位到"是哪一步做错了",而不是笼统地说"我再努力一点"。 - **失败才反思,成功直接返回**,避免无谓的额外调用。 - **反思要落库(写入 `error_pattern` 类记忆)**,否则它只对本次重试有效,无法跨任务复用;这正是 Reflexion 相比"单纯重试"的价值所在。 - **反思次数要有上限**(`max_reflections`),且反思本身也可能出错或产生错误归因,**因此反思内容应视为带适用条件的线索,而不是永远的规则**。 ## 五、生产实践与踩坑 ### Q:ReAct 的可观测性该记哪些字段? A:结论先行——**至少记录 session_id、输入、起止时间、总轮次、总 Token、工具调用明细、成功标志与最终答案;输出到日志时提炼成延迟、轮次、Token、工具调用次数、成功率几个可聚合的数值指标**。 ```python import time from dataclasses import dataclass @dataclass class ReActTrace: """ReAct 执行链路追踪""" session_id: str user_input: str start_time: float end_time: float = 0 total_iterations: int = 0 total_tokens: int = 0 tool_calls: list[dict] = None success: bool = False final_answer: str = "" @property def latency_ms(self) -> float: return (self.end_time - self.start_time) * 1000 def to_log_dict(self) -> dict: return { "session_id": self.session_id, "latency_ms": self.latency_ms, "iterations": self.total_iterations, "tokens": self.total_tokens, "tool_calls": len(self.tool_calls or []), "success": self.success } ``` **为什么要拆成 `to_log_dict`?** 因为落地到日志/监控系统时,**只应该输出可聚合的低基数指标**,而完整推理链属于高基数的排查数据,应该单独存(例如按 session_id 落到对象存储或专门的 trace 表)。把两者混在一起,会让日志成本飙升且难以聚合分析。 ### Q:生产上推荐的配置参数有哪些? A:结论先行——**核心是七个:最大迭代次数、单工具最大调用次数、工具超时、工具输出最大长度、解析重试上限、是否启用反思及其次数、是否流式输出**。 ```python # 生产推荐配置 REACT_CONFIG = { "max_iterations": 10, # 超过则强制结束,防止无限循环 "max_calls_per_tool": 5, # 单工具最大调用次数 "tool_timeout": 30.0, # 工具执行超时(秒) "max_output_length": 2000, # 工具输出最大长度 "parse_retry_limit": 2, # 格式解析失败的最大重试次数 "reflection_enabled": True, # 是否启用反思 "max_reflections": 2, # 最大反思次数 "stream_output": True, # 是否流式输出(降低首字节延迟) } ``` **这些数值是经验起点而非定律,必须结合你的模型、工具耗时分布和业务容忍度调整**(例如工具本身是慢查询时,`tool_timeout` 需要单独放大;对准确率要求高的场景可放宽 `max_iterations` 换取更多探索机会)。 ### Q:线上最常见的四类故障怎么排查? A:结论先行——**死循环靠"单工具调用上限 + 明确告知无需重试"解决;格式解析失败靠"few-shot 示例或改用 Function Calling + 换更强模型"解决;Context 超限靠"截断 + 工具内摘要 + RAG"解决;推理过多导致延迟高靠"流式输出 + 降 max_iterations + 并行工具 + 快慢模型分层"解决**。 ```text 问题 1:Agent 陷入工具调用死循环 表现:同一个工具被反复调用,参数基本相同 原因:工具返回结果不满足 Agent 期望,但 Agent 不知道怎么换策略 解决: - 设置 max_calls_per_tool 限制 - 工具返回值中明确说明"无需重试" - Prompt 中增加"如果工具多次返回相同结果,请考虑换个方法" 问题 2:输出格式持续解析失败 表现:StepType.PARSE_ERROR 反复出现 原因:LLM 不遵循格式指令(小模型常见) 解决: - Prompt 中加入 few-shot 示例 - 使用 Function Calling 替代文本格式解析 - 换更强的模型(GPT-4 vs GPT-3.5 差距明显) 问题 3:工具结果过长导致 Context 超限 表现:LLM 报 context length exceeded 原因:某个工具返回了大量文本 解决: - max_output_length 截断 - 工具内部做摘要后返回 - 使用 RAG 代替全量返回 问题 4:推理步骤过多,延迟高 表现:用户等待超过 30 秒 解决: - 启用流式输出(Streaming),减少感知等待 - 减少 max_iterations - 工具调用并行化(适合独立任务) - 使用更快的模型(如 GPT-4o-mini)处理简单步骤 ``` **补充两条实战体会**: - **问题 1 和问题 2 常常是同一个根因**:模型不遵守格式 → 解析失败 → 系统提示重写 → 模型又走了同一个"死路"。所以排查时应该先看解析失败率,再看死循环。 - **问题 4 的解法有优先级**:流式输出是"零成本"的体感优化(用户立刻看到内容在产出),应该最先做;并行化只适用于彼此独立的工具调用(如"北京和上海天气"),有依赖关系的调用强行并行会拿到错误结果。 ### Q:框架该怎么选? A:结论先行——**快速原型用 LangChain(生态最丰富、文档全),知识型 Agent 用 LlamaIndex,多 Agent 用 AutoGen 或 CrewAI;生产有性能要求时考虑手写核心循环 + 按需引入框架工具**。 | 框架 | ReAct 支持 | 特点 | 适用 | |------|-----------|------|------| | LangChain | 内置 | 生态最丰富,文档全 | 通用开发 | | LlamaIndex | 支持 | 与 RAG 结合好 | 知识型 Agent | | AutoGen | 支持 | 多 Agent 对话 | 多 Agent 系统 | | CrewAI | 支持 | 角色分工清晰 | 任务型 Agent | | 手写 | 完全自定义 | 灵活,无依赖 | 特殊需求/生产 | **为什么生产环境常推荐"手写核心循环"?** 因为 ReAct 的核心循环代码量并不大(本文的 `ReActAgent` 就是全部核心),但框架带来的抽象会遮挡对 Prompt、解析、重试、超时的精确控制,而这些恰恰是线上调优的主战场。合理策略是**先用框架快速验证价值,再把核心循环重写为可控实现,框架只保留工具连接器、向量库适配器等边缘能力**。 ### Q:上线前应该逐项核对哪些东西? A:结论先行——**核对七个点:工具清单是否动态生成、解析兜底是否有测试覆盖、工具错误信息是否可指导纠错、四个上限是否都配上、完整推理链是否落库、降级答案是否显式告知失败、高风险工具是否有审批与幂等**。 ```text ReAct 上线检查清单 □ Prompt 中的 {tools} 由 ToolRegistry 动态生成(避免与代码漂移) □ 解析器的三层兜底都有单元测试(中文格式/英文格式/畸形输出) □ 每个工具的错误返回都包含"原因 + 期望格式/期望参数" □ 已配置:max_iterations / max_calls_per_tool / tool_timeout / max_output_length □ 每轮的 steps(含 raw_output)已持久化,可按 session_id 回溯 □ 超限或失败时返回的是明确告知失败的降级答案,而非空字符串 □ 有副作用的工具:权限校验 + 幂等键 + 必要时人工审批 ``` **这份清单里最容易漏的是第三项和第六项**。第三项漏了,模型拿到 `None` 式错误只能盲目重试,轮数被白白耗光;第六项漏了,用户会以为任务成功,**静默失败比显式失败危害大得多**——它会污染用户对系统可靠性的判断,而且没有告警信号。 ## 小结 - **ReAct 工程化的核心矛盾是"模型输出不可靠",三块补丁分别是:多层解析器、安全调度层、可观测与配置兜底。** - **Prompt 要用半结构化协议**定义输出格式与行为约束,让输出可被程序解析。 - **解析器分三层容错**:多套正则 → JSON 修复 → 启发式兜底;解析失败是正常分支,不应中断循环。 - **工具层要四层防护**:黑名单、频率上限、输入校验、输出截断;错误信息必须有信息量,模型才可能自纠。 - **变体按需加**:Memory 补个性化、Critic 补准确率、Reflexion 补自我改进、Plan-then-ReAct 补复杂结构、Multi-Agent 补专业分工。 - **生产必须有安全阀**:`max_iterations`、`max_calls_per_tool`、超时、截断、降级提示,一个都不能少。 ## 思考题 1. 为什么 ReAct 的循环里"解析错误"也要当作一种正常步骤类型来处理,而不是直接抛异常? - **参考答案:** 因为 LLM 输出格式不稳定是常态而非异常。把解析失败显式建模成 `PARSE_ERROR`,系统就能把"格式不对,请重写"作为 Observation 回灌给模型,从而获得一次自纠机会;同时失败记录会进入 `steps`,成为排查与评测的数据。直接抛异常会让一次格式抖动导致整个任务中断。 2. 工具执行层的 `_validate_input` 用关键字黑名单能防住注入吗?它的边界在哪? - **参考答案:** 防不住。字符串拼接、编码变形等方式都能绕过关键字匹配,它只能作为最后一道提醒。真正的隔离要在能力层面做:工具只授予最小权限(只读账号、命令白名单)、执行环境沙箱化、高风险操作前置审批与幂等键。 3. `max_calls_per_tool` 与 `max_iterations` 这两个上限分别防的是什么? - **参考答案:** `max_iterations` 防的是整体不收敛(无论调用什么工具都停不下来,或持续解析失败空转);`max_calls_per_tool` 防的是针对单个工具的死循环(同参反复调用、工具结果不满足期望时不会换策略)。两者是总量约束与单点约束的关系,缺一不可。 4. 为什么生产级 `run` 要返回完整的 `steps` 推理链,而不只返回 `answer`? - **参考答案:** 完整推理链是可观测性与评测的原料:能定位答错发生在哪一步(选错工具/参数错/误判结果)、统计平均轮次与工具失败率、支撑线上问题复盘。只返回答案的 Agent 无法被诊断和优化。 5. 什么时候应该从"标准 ReAct"升级到带 Reflection 或 Multi-Agent 的变体? - **参考答案:** 当标准 ReAct 在某个具体指标上确实不达标时再针对性补:需要跨重试做自我改进用 Reflection;需要专业分工或隔离权限用 Multi-Agent。每次升级都会增加 LLM 调用次数与协调成本,因此应以指标驱动的按需引入为原则,而不是默认堆最复杂的形态。
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入