Langfuse怎么用？从LLM调用追踪到Prompt管理与评测的实用指南

先明确要排查的请求与采集边界

Langfuse可用于记录LLM应用的执行过程、管理提示词，并关联评测结果。以下以“检索知识库后生成回答”为示例：用户提问后，应用检索资料、拼接上下文、调用模型并返回答案。目标不是只看到最终文本，而是定位哪个步骤慢、在哪里失败，以及回答是否有依据。

接入前先列出允许采集的字段。密钥、访问令牌不应进入记录；用户问题、检索片段和模型输出可能含个人信息或内部资料，应按业务要求脱敏、截断或不采集。异常消息也要检查，避免其中夹带完整请求。不要等数据上传后才处理敏感内容。

理解Trace、Span与生成记录

• Trace：组织一次应用请求的完整执行链路，可关联请求标识、输入输出及业务元数据。
• Span：表示一个有起止时间的执行步骤，例如检索、文档重排或结果解析，可以形成父子层级。
• 生成记录：专门描述模型调用，可记录模型、输入输出、参数，以及实际可获得的用量信息。

例如，一条问答Trace下先有“知识库检索”Span，再有“答案生成”记录。并行执行或嵌套执行时，要保留正确的父子关系；否则虽然能看到记录，却难以还原请求路径。生成记录不等于质量评测，它首先说明模型调用发生了什么。

按步骤接入，并用一次测试请求验收

1. 在Langfuse项目中获取接入配置，按所选部署方式设置服务地址与凭据；凭据放入环境变量或密钥管理服务，不写入提示词。
2. 选择与应用技术栈及SDK版本匹配的接入方式，在请求入口建立追踪上下文，并让检索和模型调用沿用该上下文。
3. 为检索步骤记录开始、结束、返回条数和必要的过滤条件；为模型调用建立生成记录，写入允许采集的模型参数、输入及输出。
4. 在异常路径记录失败状态与脱敏后的错误信息，确保步骤结束。短生命周期脚本还应按SDK要求等待记录发送完成。
5. 提交一条不含敏感信息的测试问题，在界面确认各步骤属于同一条Trace，层级、时间和成功或失败状态符合预期。

不要假设所有框架和模型都会自动提供全部字段。输入与输出token数需要模型接口返回，或由明确配置的估算方式提供；缺失不能当作零。费用数据依赖用量及计价配置，也不能直接视为账单。

沿时间线排查慢请求或失败

假设某次问答耗时8秒，其中检索耗时5秒、生成耗时2秒，其余时间用于应用处理。这只是排查示例，并非实测结果。此时应先检查检索服务、过滤条件和重试，而不是直接更换模型。若检索很快但生成缓慢，再查看上下文长度、输出长度及调用参数。

若请求失败，先定位报错节点：检索超时、模型接口报错与输出解析失败需要分别处理。总耗时不能简单等于所有步骤耗时之和，因为步骤可能并行或嵌套。流式返回时，也应区分首段响应时间与完整生成耗时，并确认实际采集了哪一种指标。

把提示词变成可定位的版本

可创建名为“知识库问答”的提示词，模板写为：“仅依据以下资料回答；资料不足时明确说明。资料：{{context}}；问题：{{question}}。”应用按名称及指定版本或标签获取提示词，填入变量，再交给模型调用。

修改约束后保存新版本，并在生成记录中关联实际使用的提示词及版本。比较测试时固定版本；生产环境若通过标签切换版本，还要明确缓存刷新策略。仅修改平台上的模板，并不意味着已经发出的请求或缓存内容会同步改变。

用固定样本比较，而非凭印象选版本

准备一组固定问题，覆盖有明确答案、资料不足和容易混淆的场景，为每条样本保留输入、参考资料及验收标准。让两个提示词版本分别运行同一组样本，尽量固定模型、参数和检索上下文，并记录各自的追踪与评测结果。

检查事实是否有资料支持、资料不足时是否承认未知、格式是否符合要求，再比较延迟与用量。自动评分可以辅助筛选，但评审模型也可能误判；应人工复核低分、版本间分歧和关键业务样本。最终选择应同时依据质量与运行成本，不能因为调用成功或耗时更短，就认定回答更可靠。