开篇AI 应用没有日志就是黑盒大模型应用最怕的不是慢也不是贵。最怕的是用户说答案错了你不知道错在哪。普通业务系统出了问题看接口日志、SQL 日志、异常堆栈大多能定位。但大模型应用不一样。一次回答背后可能经过问题改写、意图识别、知识库检索、Rerank、Prompt 拼接、模型调用、工具调用、多轮记忆、结构化输出和安全拦截。任何一层出错最后答案都会跑偏。一、为什么传统日志不够用传统日志看的是“接口是否正常执行”。大模型日志看的是“答案为什么这样生成”。这两件事不是一个维度。比如用户问企业制度最终答案错了。原因可能不是模型弱而是问题改写错了Retriever 没召回正确文档Rerank 把关键 Chunk 排到后面Prompt 把上下文拼反了工具返回了旧数据Memory 把上一个用户的状态串进来了。所以 AI 日志必须从“结果日志”升级成“过程日志”。不只记录 final answer还要记录每一步的输入、输出、版本、耗时、分数、错误和关联 ID。二、一次回答必须留下完整证据链真正可上线的 AI 系统每一次回答都应该能回答 7 个问题谁问的系统怎么理解的用了哪些资料Prompt 怎么拼的调用了哪个模型执行了哪些工具用户反馈如何这条证据链的价值很直接当答案出错时不用猜当成本升高时不用拍脑袋当效果下降时可以回放历史 Trace对比模型版本、Prompt 版本、检索策略和工具返回。三、AI 日志字段怎么设计日志字段不要贪多也不能太少。最少要覆盖请求、输入、检索、Prompt、模型、工具、记忆、输出和反馈 9 层。每一层都对应一个排查入口。字段设计的原则能复盘的才有价值。不能定位问题、不能计算指标、不能沉淀评测集的字段不要乱记。四、LangSmith 的 Trace / Run / Thread 给了我们标准答案LangSmith 的数据结构很适合借鉴。它把一个应用或服务放在 Project 里一次完整操作是 TraceTrace 由多个 Run 组成多轮会话可以用 Thread 把多个 Trace 串起来。官方文档也明确说明Run 可以代表一次 LLM 调用、Prompt 格式化、检索调用或其他离散操作。这套结构非常适合大模型应用日志request_id 对应业务请求trace_id 对应一次 AI 任务run_id 对应每个子步骤parent_run_id 还原调用树。Project一个应用或服务例如 customer-service-agent、stock-analysis-agent。Trace一次用户请求的完整执行链路。Run链路里的一个步骤例如 Retriever、Tool、LLM、Parser。Thread多轮会话把多次 Trace 按 conversation_id / thread_id 关联。Metadata / Tags用于写入环境、版本、用户、渠道、业务场景、Prompt 版本等筛选字段。五、源码级理解Callback 是 LangChain 的日志切入点LangChain 的日志体系不是在最后统一 print。它在框架生命周期里埋点。模型开始、模型结束、工具开始、工具结束、检索开始、检索结束、Chain 开始、Chain 结束这些都是事件。源码里CallbackManager 会维护一组 CallbackHandler。事件发生时manager 调用 handle_event把 on_llm_start、on_llm_end、on_tool_start、on_tool_end 等事件分发给所有 handler。每个 handler 可以选择写 LangSmith、写控制台、写自建数据库或者写 MQ。这就是为什么日志系统应该做成“观察者”而不是散落在业务代码里。业务链路负责执行Callback / Middleware 负责采集。六、源码链路压缩成一句话Runnable.invoke() → CallbackManager.configure() → on_chain_start() 创建 Run → get_child() 传递 parent_run_id → LLM / Retriever / Tool 触发 start/end/error → CallbackHandler 写入 LangSmith 或自建日志。这里有三个关键点。第一run_id 是每个步骤的身份。第二parent_run_id 把子步骤挂回父步骤。第三tags 和 metadata 会随着子 run 继承下去所以你可以在根请求写入 user_id、env、prompt_version、biz_scene后面的 LLM、Tool、Retriever 都能带上。源码里的 BaseRunManager 会持有 run_id、parent_run_id、tags、metadata 和 handlers。CallbackManagerForLLMRun 负责 LLM 相关事件例如新 token、结束、异常。CallbackManagerForChainRun 负责 chain 事件。Tool、Retriever 也有自己的 manager。每个 manager 都是在做一件事把生命周期事件变成可观测数据。七、答案错了日志怎么帮你定位有日志之后排查路径会非常清楚。不要一上来就说“模型幻觉”。先看链路。先看 original_question 和 rewritten_question确认问题有没有被改歪。再看 intent 和 route确认是不是走错了 FAQ / RAG / Tool / Agent。再看 retriever topK 和 score确认资料有没有召回。再看 rerank_score确认正确资料有没有被排掉。再看 prompt_version 和 final_prompt_hash确认上下文和模板是否正确。再看 tool_args 和 tool_result确认外部系统有没有返回旧数据或错误数据。最后再看模型参数、temperature、finish_reason、token 截断和最终输出。八、自建日志库怎么设计LangSmith 适合调试、追踪和评测。但企业系统通常还需要自建日志库。原因很简单你要和用户、订单、权限、业务场景、工单、反馈、告警打通。推荐设计成“主表 子表”。主表记录一次请求的总览子表记录每类细节。不要把所有东西塞进一张大 JSON 表否则后面查询、统计、回放都会痛苦。ai_request_log一次请求的主记录保存问题、答案、状态、总耗时、trace_id。ai_run_log所有子步骤的通用运行表保存 run_id、parent_run_id、run_type。ai_model_call_log模型调用明细保存模型、token、成本、耗时、finish_reason。ai_retrieval_log检索明细保存 query、doc_id、chunk_id、score、rerank_score、source。ai_tool_call_log工具调用明细保存 tool_name、args、result、error、retry。ai_feedback_log用户反馈、人工标注、评测分数和失败分类。九、企业级落地Java 主服务 Python AI 服务在真实项目里不建议让 Python AI 服务承担所有日志治理。更合理的是Java 主服务负责业务身份和请求主链路Python AI 服务负责 LangChain 事件采集异步队列负责削峰日志存储负责查询和分析LangSmith 负责 Trace 可视化。Java 主服务生成 request_id并把 user_id、tenant_id、biz_scene、channel 写进请求上下文。Python AI 服务接收到这些上下文后放入 RunnableConfig 的 metadata / tags 或 Agent runtime context。模型、工具、检索、记忆的所有事件都带着这些元数据最后才能按用户、场景、模型版本、Prompt 版本聚合分析。十、日志不是越全越好还要脱敏、采样、异步AI 日志很容易踩坑。最常见的是把完整 Prompt、用户隐私、工具返回、订单数据全部明文落库。短期看方便排查长期就是安全风险。敏感字段必须脱敏手机号、身份证、邮箱、地址、token、cookie、API Key、银行卡。Prompt 可以保存 hash、版本和变量摘要完整内容按权限查看或短期留存。工具参数和返回要分级普通字段可记录敏感字段只记录 hash 或脱敏值。日志写入要异步化不能阻塞主回答链路。大流量场景要采样但失败请求、低分请求、人工差评请求必须全量保存。保留周期要分层明细短期留聚合指标长期留。十一、日志如何变成评测闭环日志不是终点。日志真正的价值是把线上失败样本沉淀为评测集。LangSmith 的 Evaluation 工作流也强调离线评测可以在上线前基于数据集测试版本在线评测可以在生产环境监控真实交互失败生产样本可以加入数据集再通过离线实验验证修复效果。这个思路也应该进入自建系统。用户点踩或人工标注失败写入 ai_feedback_log。系统根据 failure_type 分类召回失败、Prompt 失败、工具失败、模型幻觉、格式错误。失败样本进入 eval_dataset。每次改 Prompt、改模型、改检索策略都跑一次离线回归。上线后继续做在线抽样评测观察准确率、延迟、成本和差评率。十二、上线检查清单十三、总结大模型应用的日志体系核心不是“把输出存下来”。核心是把一次回答拆成可复盘的运行链路。一套合格的日志体系应该同时服务四件事线上排障、效果评测、成本治理、产品迭代。没有日志AI 应用就是黑盒有了证据链AI 应用才真正可控。内容来源https://news.eeebb.com/article/3710
大模型应用日志体系、Callback 源码链路、Trace 复盘、企业级落地
发布时间：2026/6/16 16:29:20
开篇AI 应用没有日志就是黑盒大模型应用最怕的不是慢也不是贵。最怕的是用户说答案错了你不知道错在哪。普通业务系统出了问题看接口日志、SQL 日志、异常堆栈大多能定位。但大模型应用不一样。一次回答背后可能经过问题改写、意图识别、知识库检索、Rerank、Prompt 拼接、模型调用、工具调用、多轮记忆、结构化输出和安全拦截。任何一层出错最后答案都会跑偏。一、为什么传统日志不够用传统日志看的是“接口是否正常执行”。大模型日志看的是“答案为什么这样生成”。这两件事不是一个维度。比如用户问企业制度最终答案错了。原因可能不是模型弱而是问题改写错了Retriever 没召回正确文档Rerank 把关键 Chunk 排到后面Prompt 把上下文拼反了工具返回了旧数据Memory 把上一个用户的状态串进来了。所以 AI 日志必须从“结果日志”升级成“过程日志”。不只记录 final answer还要记录每一步的输入、输出、版本、耗时、分数、错误和关联 ID。二、一次回答必须留下完整证据链真正可上线的 AI 系统每一次回答都应该能回答 7 个问题谁问的系统怎么理解的用了哪些资料Prompt 怎么拼的调用了哪个模型执行了哪些工具用户反馈如何这条证据链的价值很直接当答案出错时不用猜当成本升高时不用拍脑袋当效果下降时可以回放历史 Trace对比模型版本、Prompt 版本、检索策略和工具返回。三、AI 日志字段怎么设计日志字段不要贪多也不能太少。最少要覆盖请求、输入、检索、Prompt、模型、工具、记忆、输出和反馈 9 层。每一层都对应一个排查入口。字段设计的原则能复盘的才有价值。不能定位问题、不能计算指标、不能沉淀评测集的字段不要乱记。四、LangSmith 的 Trace / Run / Thread 给了我们标准答案LangSmith 的数据结构很适合借鉴。它把一个应用或服务放在 Project 里一次完整操作是 TraceTrace 由多个 Run 组成多轮会话可以用 Thread 把多个 Trace 串起来。官方文档也明确说明Run 可以代表一次 LLM 调用、Prompt 格式化、检索调用或其他离散操作。这套结构非常适合大模型应用日志request_id 对应业务请求trace_id 对应一次 AI 任务run_id 对应每个子步骤parent_run_id 还原调用树。Project一个应用或服务例如 customer-service-agent、stock-analysis-agent。Trace一次用户请求的完整执行链路。Run链路里的一个步骤例如 Retriever、Tool、LLM、Parser。Thread多轮会话把多次 Trace 按 conversation_id / thread_id 关联。Metadata / Tags用于写入环境、版本、用户、渠道、业务场景、Prompt 版本等筛选字段。五、源码级理解Callback 是 LangChain 的日志切入点LangChain 的日志体系不是在最后统一 print。它在框架生命周期里埋点。模型开始、模型结束、工具开始、工具结束、检索开始、检索结束、Chain 开始、Chain 结束这些都是事件。源码里CallbackManager 会维护一组 CallbackHandler。事件发生时manager 调用 handle_event把 on_llm_start、on_llm_end、on_tool_start、on_tool_end 等事件分发给所有 handler。每个 handler 可以选择写 LangSmith、写控制台、写自建数据库或者写 MQ。这就是为什么日志系统应该做成“观察者”而不是散落在业务代码里。业务链路负责执行Callback / Middleware 负责采集。六、源码链路压缩成一句话Runnable.invoke() → CallbackManager.configure() → on_chain_start() 创建 Run → get_child() 传递 parent_run_id → LLM / Retriever / Tool 触发 start/end/error → CallbackHandler 写入 LangSmith 或自建日志。这里有三个关键点。第一run_id 是每个步骤的身份。第二parent_run_id 把子步骤挂回父步骤。第三tags 和 metadata 会随着子 run 继承下去所以你可以在根请求写入 user_id、env、prompt_version、biz_scene后面的 LLM、Tool、Retriever 都能带上。源码里的 BaseRunManager 会持有 run_id、parent_run_id、tags、metadata 和 handlers。CallbackManagerForLLMRun 负责 LLM 相关事件例如新 token、结束、异常。CallbackManagerForChainRun 负责 chain 事件。Tool、Retriever 也有自己的 manager。每个 manager 都是在做一件事把生命周期事件变成可观测数据。七、答案错了日志怎么帮你定位有日志之后排查路径会非常清楚。不要一上来就说“模型幻觉”。先看链路。先看 original_question 和 rewritten_question确认问题有没有被改歪。再看 intent 和 route确认是不是走错了 FAQ / RAG / Tool / Agent。再看 retriever topK 和 score确认资料有没有召回。再看 rerank_score确认正确资料有没有被排掉。再看 prompt_version 和 final_prompt_hash确认上下文和模板是否正确。再看 tool_args 和 tool_result确认外部系统有没有返回旧数据或错误数据。最后再看模型参数、temperature、finish_reason、token 截断和最终输出。八、自建日志库怎么设计LangSmith 适合调试、追踪和评测。但企业系统通常还需要自建日志库。原因很简单你要和用户、订单、权限、业务场景、工单、反馈、告警打通。推荐设计成“主表 子表”。主表记录一次请求的总览子表记录每类细节。不要把所有东西塞进一张大 JSON 表否则后面查询、统计、回放都会痛苦。ai_request_log一次请求的主记录保存问题、答案、状态、总耗时、trace_id。ai_run_log所有子步骤的通用运行表保存 run_id、parent_run_id、run_type。ai_model_call_log模型调用明细保存模型、token、成本、耗时、finish_reason。ai_retrieval_log检索明细保存 query、doc_id、chunk_id、score、rerank_score、source。ai_tool_call_log工具调用明细保存 tool_name、args、result、error、retry。ai_feedback_log用户反馈、人工标注、评测分数和失败分类。九、企业级落地Java 主服务 Python AI 服务在真实项目里不建议让 Python AI 服务承担所有日志治理。更合理的是Java 主服务负责业务身份和请求主链路Python AI 服务负责 LangChain 事件采集异步队列负责削峰日志存储负责查询和分析LangSmith 负责 Trace 可视化。Java 主服务生成 request_id并把 user_id、tenant_id、biz_scene、channel 写进请求上下文。Python AI 服务接收到这些上下文后放入 RunnableConfig 的 metadata / tags 或 Agent runtime context。模型、工具、检索、记忆的所有事件都带着这些元数据最后才能按用户、场景、模型版本、Prompt 版本聚合分析。十、日志不是越全越好还要脱敏、采样、异步AI 日志很容易踩坑。最常见的是把完整 Prompt、用户隐私、工具返回、订单数据全部明文落库。短期看方便排查长期就是安全风险。敏感字段必须脱敏手机号、身份证、邮箱、地址、token、cookie、API Key、银行卡。Prompt 可以保存 hash、版本和变量摘要完整内容按权限查看或短期留存。工具参数和返回要分级普通字段可记录敏感字段只记录 hash 或脱敏值。日志写入要异步化不能阻塞主回答链路。大流量场景要采样但失败请求、低分请求、人工差评请求必须全量保存。保留周期要分层明细短期留聚合指标长期留。十一、日志如何变成评测闭环日志不是终点。日志真正的价值是把线上失败样本沉淀为评测集。LangSmith 的 Evaluation 工作流也强调离线评测可以在上线前基于数据集测试版本在线评测可以在生产环境监控真实交互失败生产样本可以加入数据集再通过离线实验验证修复效果。这个思路也应该进入自建系统。用户点踩或人工标注失败写入 ai_feedback_log。系统根据 failure_type 分类召回失败、Prompt 失败、工具失败、模型幻觉、格式错误。失败样本进入 eval_dataset。每次改 Prompt、改模型、改检索策略都跑一次离线回归。上线后继续做在线抽样评测观察准确率、延迟、成本和差评率。十二、上线检查清单十三、总结大模型应用的日志体系核心不是“把输出存下来”。核心是把一次回答拆成可复盘的运行链路。一套合格的日志体系应该同时服务四件事线上排障、效果评测、成本治理、产品迭代。没有日志AI 应用就是黑盒有了证据链AI 应用才真正可控。内容来源https://news.eeebb.com/article/3710
