什么是 回调处理器（Callback Handler）？
回调处理器（Callback Handler）是生命周期钩子组件，接收模型调用、工具、检索器、流或编排节点产生的事件，用于日志、追踪、指标、调试、审计或策略执行。
工作原理
回调处理器是 AI 应用框架的埋点层。它不把日志和追踪代码嵌入每个模型、工具、检索器或图节点，而是接收标准化生命周期事件，例如开始、结束、错误、token、流式分片、工具调用、检索结果和节点转换。这种分离让业务逻辑更干净，也让 AI 应用可以接入 OpenTelemetry、审计日志、成本看板、评估系统或实时用户界面。
主要特点
- 生命周期事件接口：观察开始、结束、错误、token、流、工具调用、检索和节点转换
- 关注点分离：把可观测性和策略钩子放在核心业务逻辑之外
- 流式支持：可以把 token 或分片事件低延迟转发到用户界面
- 运行价值：支持成本追踪、延迟分析、调试、评估和故障响应
- 安全要求：必须避免把敏感提示词、检索文档或工具输出泄露到日志
常见用途
- 为每次模型调用、工具调用和图节点创建 OpenTelemetry Span
- 把模型部分输出流式推送到网页或聊天界面
- 记录 token 用量、延迟、错误类型和供应商请求 ID
- 捕获 Agent 轨迹用于调试和评估
- 当 Agent 尝试敏感动作时执行审计策略
示例
loading...
Loading code...常见问题
回调处理器应该捕获哪些事件？
有价值的事件包括组件开始和结束、模型 token、流式分片、工具调用、检索结果、错误、重试、图节点转换和最终输出。具体事件集合取决于框架。
回调处理器和可观测性有什么关系？
回调提供可观测系统需要的原始生命周期事件。它们可以创建追踪、指标、日志、成本记录和审计事件，同时避免污染应用业务逻辑。
回调会改变应用行为吗？
有些回调只做观察，有些可能执行策略、取消执行、脱敏数据或请求人工审批。团队应区分只读回调和会改变行为的回调。
回调日志的主要风险是什么？
主要风险是泄露敏感数据。提示词、检索文档、用户数据、工具输出和凭据都必须根据隐私和安全要求进行脱敏或排除。