Langfuse 实战：部署、埋点、评估，跑通 LLM 可观测全流程（TaoToken 统一 Key 接入版）

1. 为什么你的 LLM 应用需要 LangfuseLangfuse 是一个开源的 LLM 可观测平台能帮你把每次模型调用的输入、输出、token 消耗、延迟、错误全部记录下来并且支持在这些数据上跑评估任务。它适合正在做 RAG、Agent、多轮对话应用的开发者尤其是那些已经上线但排查问题只能靠翻日志的人。我遇到过最典型的情况用户反馈回答质量下降但你不知道是哪一步出了问题。是检索召回了无关文档是 prompt 改坏了还是模型本身波动普通日志只能告诉你请求成功/失败而 Langfuse 能给你一条完整的 trace——从用户输入到检索、到拼 prompt、到模型返回每一步的耗时和内容都清清楚楚。这篇文章会带你走完三段核心流程用 Docker Compose 把 Langfuse 跑起来、用 SDK 给 LLM 调用加埋点、在 trace 数据上配置评估任务。同时我会演示怎么通过 TaoToken 的统一 API 通道接入模型调用这样你不需要在多个模型供应商之间来回切换 Key 和计费方式。整个流程跑通后你能得到的东西很具体一个本地可访问的 Langfuse 面板、一条完整的 RAG trace 记录、以及一份自动生成的评估分数。下面直接开始。2. 部署前的准备TaoToken 统一 Key 与 Langfuse 环境2.1 为什么用 TaoToken 接入模型调用Langfuse 本身不提供模型能力它只负责记录和评估。你的 LLM 调用需要走一个模型 API而 TaoToken 提供的是统一 Key 和统一 API 通道——你只需要一个 Key就能调用不同供应商的模型不用为每个模型单独申请账号、单独管理计费。对于 Langfuse 的评估环节来说这一点尤其方便LLM-as-a-Judge 需要额外调用模型来打分如果评估模型和被评估模型走的是不同通道Key 管理会很乱。统一走 TaoToken 之后埋点和评估用的是同一套凭证。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI SDK 的调用格式。你需要在官网注册后到控制台创建 API Key地址是https://taotoken.net/console/api-keys。创建完成后保存好后面配置环境变量会用到。2.2 Langfuse 自托管的最低要求Langfuse v3 采用双数据库架构PostgreSQL 存元数据项目、用户、prompt 版本ClickHouse 存 trace 数据每次调用的详细信息。Docker Compose 会拉起 6 个服务web、worker、PostgreSQL、ClickHouse、Redis、MinIO。资源方面最低建议 4 核 8G 内存。如果只是本地开发测试2 核 4G 也能跑起来但 ClickHouse 的查询会慢一些。磁盘预留 20G 以上trace 数据积累速度取决于你的调用量。你需要提前安装好 Docker 和 Docker Compose。确认版本docker --version docker compose version如果docker compose version报错说明你装的是旧版docker-compose建议升级到 Compose V2因为下面的配置文件用的是 V2 语法。3. 可复制的 docker-compose 配置与启动3.1 完整 docker-compose.yml把下面的内容保存为docker-compose.yml。这份配置基于 Langfuse 官方仓库的示例做了精简保留了核心服务去掉了本地开发才需要的额外依赖。services: langfuse-web: image: langfuse/langfuse:3 depends_on: postgres: condition: service_healthy clickhouse: condition: service_healthy redis: condition: service_healthy ports: - 3000:3000 environment: DATABASE_URL: postgresql://postgres:postgrespostgres:5432/langfuse CLICKHOUSE_URL: http://clickhouse:8123 CLICKHOUSE_USER: default CLICKHOUSE_PASSWORD: clickhouse REDIS_HOST: redis REDIS_PORT: 6379 REDIS_AUTH: redispass NEXTAUTH_URL: http://localhost:3000 NEXTAUTH_SECRET: mysecret SALT: mysalt ENCRYPTION_KEY: 0000000000000000000000000000000000000000000000000000000000000000 TELEMETRY_ENABLED: false langfuse-worker: image: langfuse/langfuse-worker:3 depends_on: postgres: condition: service_healthy clickhouse: condition: service_healthy redis: condition: service_healthy environment: DATABASE_URL: postgresql://postgres:postgrespostgres:5432/langfuse CLICKHOUSE_URL: http://clickhouse:8123 CLICKHOUSE_USER: default CLICKHOUSE_PASSWORD: clickhouse REDIS_HOST: redis REDIS_PORT: 6379 REDIS_AUTH: redispass SALT: mysalt ENCRYPTION_KEY: 0000000000000000000000000000000000000000000000000000000000000000 TELEMETRY_ENABLED: false postgres: image: postgres:16 environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres POSTGRES_DB: langfuse volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 5s timeout: 5s retries: 10 clickhouse: image: clickhouse/clickhouse-server:24 environment: CLICKHOUSE_USER: default CLICKHOUSE_PASSWORD: clickhouse volumes: - clickhouse_data:/var/lib/clickhouse healthcheck: test: [CMD, wget, --spider, -q, http://localhost:8123/ping] interval: 5s timeout: 5s retries: 10 redis: image: redis:7 command: redis-server --requirepass redispass volumes: - redis_data:/data healthcheck: test: [CMD, redis-cli, -a, redispass, ping] interval: 5s timeout: 5s retries: 10 volumes: postgres_data: clickhouse_data: redis_data:几个关键配置项说明。SALT和ENCRYPTION_KEY用于加密存储 API Key生产环境务必用openssl rand -hex 32生成随机值替换。NEXTAUTH_SECRET用于会话签名同样要换成随机字符串。TELEMETRY_ENABLED设为 false 可以关闭匿名使用数据上报。3.2 启动与初始化在配置文件所在目录执行docker compose up -d首次启动需要拉取镜像视网络情况可能需要几分钟。启动完成后检查服务状态docker compose ps六个服务都应该是running或healthy状态。如果某个服务反复重启用docker compose logs 服务名查看日志。确认全部就绪后浏览器访问http://localhost:3000你会看到 Langfuse 的注册页面。注册一个账号登录后创建一个 Project。进入 Project Settings → API Keys点击创建你会得到一对 Keypk-lf-...Public Key和sk-lf-...Secret Key。这两个值后面埋点要用。4. SDK 埋点让每次 LLM 调用都留下痕迹4.1 安装依赖与配置环境变量Python 环境下安装 Langfuse SDK 和 OpenAI SDKpip install langfuse openai设置环境变量。把下面的内容写入.env文件或者直接在终端 exportexport LANGFUSE_PUBLIC_KEYpk-lf-你的public-key export LANGFUSE_SECRET_KEYsk-lf-你的secret-key export LANGFUSE_HOSThttp://localhost:3000 export OPENAI_API_KEY你的TaoToken-Key export OPENAI_BASE_URLhttps://taotoken.net/api这里的关键点是OPENAI_BASE_URL指向 TaoToken 的 API 地址。这样你的模型调用走 TaoToken 通道而 Langfuse 的埋点 SDK 会自动捕获这些调用并上报到本地 Langfuse 实例。4.2 用 drop-in 替换捕获 OpenAI 调用Langfuse 提供了 OpenAI SDK 的 drop-in 替换改一行 import 就能自动上报所有chat.completions.create调用from langfuse.openai import openai response openai.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个简洁的助手。}, {role: user, content: 用一句话解释什么是 LLM 可观测。} ] ) print(response.choices[0].message.content)运行这段代码后打开 Langfuse 面板的 Traces 页面你应该能看到一条新的 trace 记录。点进去可以看到完整的输入消息、模型返回内容、token 用量和延迟。不需要显式初始化 Langfuse 客户端SDK 会读取环境变量自动完成配置。4.3 用 observe 装饰器追踪 RAG 全链路drop-in 替换只能捕获模型调用本身。如果你的应用有检索、重排序、prompt 拼接等步骤需要用observe()装饰器把这些自定义逻辑也纳入 tracefrom langfuse import observe from langfuse.openai import openai observe() def retrieve_documents(query: str) - list: # 模拟检索实际替换为你的向量库查询 return [ Langfuse 是一个 LLM 可观测平台。, 它支持 trace、评估和 prompt 管理。 ] observe() def generate_answer(query: str, docs: list) - str: context \n.join(docs) response openai.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: f基于以下上下文回答\n{context}}, {role: user, content: query} ] ) return response.choices[0].message.content observe() def rag_pipeline(query: str) - str: docs retrieve_documents(query) return generate_answer(query, docs) result rag_pipeline(Langfuse 能做什么) print(result)observe()会自动把函数调用链串联成一条完整的 trace。rag_pipeline是根 spanretrieve_documents和generate_answer是子 span嵌套关系自动建立。在 Langfuse UI 里你能看到整条链路的执行顺序、每步耗时和输入输出。4.4 手动创建 span 记录关键指标有些场景下你需要记录额外的指标比如检索召回了多少文档、重排序后的分数分布。可以用langfuse_context手动更新当前 spanfrom langfuse import observe, langfuse_context observe() def retrieve_documents(query: str) - list: docs [文档A, 文档B, 文档C] langfuse_context.update_current_observation( metadata{doc_count: len(docs), retriever: vector_search} ) return docs这样在 trace 详情里就能看到自定义的 metadata排查问题时能快速定位是检索数量不够还是排序有问题。5. 验证请求与评估任务配置5.1 确认 trace 上报成功运行完上面的 RAG 代码后回到 Langfuse 面板。在 Traces 列表里应该能看到一条名为rag_pipeline的记录。点进去检查三件事第一根 span 下面是否挂载了retrieve_documents和generate_answer两个子 span。第二generate_answer里是否包含模型调用的详细信息包括 model 名称、token 用量、延迟。第三metadata 里是否有你手动写入的doc_count。如果 trace 列表为空先检查环境变量是否在当前终端生效再确认 Langfuse 服务是否正常运行。SDK 采用异步批量上报默认间隔几秒稍等片刻刷新页面。5.2 配置 LLM-as-a-Judge 评估trace 数据有了之后下一步是在这些数据上跑评估。Langfuse 支持三种评估方式最常用的是 LLM-as-a-Judge——让另一个模型来给你的输出打分。在 Langfuse 面板进入 Evaluations 页面创建一个新的 evaluator类型选择 LLM-as-a-Judge。评分 prompt 模板可以这样写你是一个评审。请根据以下标准评判 AI 的回答 - 是否直接回答了用户的问题 - 是否包含事实错误 - 回答是否简洁 用户问题{{input}} AI 回答{{output}} 请输出一个 1-5 的整数分数不需要其他内容。配置评估模型时同样走 TaoToken 通道。在 evaluator 的模型设置里填入 TaoToken 的 API 地址和你的 Key选择gpt-4o-mini作为评审模型。这样评估调用和业务调用共用一套凭证不需要额外管理。保存 evaluator 后Langfuse 会在新的 trace 数据上自动执行评分结果汇总到 Score Analytics 面板。你可以按时间、按模型、按 prompt 版本筛选查看分数分布。5.3 用 Code Evaluator 做精确检查LLM-as-a-Judge 适合评估主观质量但有些指标需要精确判断比如回答里是否包含引用标记、输出格式是否符合 JSON schema。这类场景用 Code Evaluatordef evaluate(output: str, expected: dict) - float: if 参考文献 in output: return 1.0 return 0.0在 Langfuse 的 Evaluations 页面创建 Code Evaluator把函数逻辑粘贴进去。Langfuse 会在每条 trace 上执行这个函数返回的分数记录到对应的 trace 上。5.4 用 Dataset Experiment 做版本对比当你改了 prompt 或者换了模型需要确认效果有没有变差。这时候用 Dataset 和 Experiment。先在 Datasets 页面创建一个数据集手动添加几条测试用例每条包含 input 和 expected_output。然后创建一个 Experiment选择数据集、选择要对比的 prompt 版本或模型配置运行。Langfuse 会在数据集上逐条执行自动计算平均分、通过率等指标。你可以同时跑两个 Experiment一个用旧 prompt一个用新 prompt在面板上直接对比分数差异。分数下降就回滚上升就推到生产。6. 本篇常见排查服务启动后访问 3000 端口报错。先确认docker compose ps里所有服务都是 healthy。如果 web 服务正常但页面报 500大概率是 PostgreSQL 或 ClickHouse 还没完全就绪。等 30 秒再刷新或者查看docker compose logs langfuse-web里的错误信息。trace 列表一直为空。检查三个地方环境变量LANGFUSE_PUBLIC_KEY和LANGFUSE_SECRET_KEY是否设置正确LANGFUSE_HOST是否指向http://localhost:3000SDK 是否正常安装。可以在代码里加一行from langfuse import Langfuse; Langfuse().auth_check()来验证连接。模型调用报 401 或 403。确认OPENAI_API_KEY填的是 TaoToken 的 KeyOPENAI_BASE_URL填的是https://taotoken.net/api。如果 Key 没问题到 TaoToken 控制台检查余额和权限。评估任务不执行。LLM-as-a-Judge 需要额外的模型调用确认 evaluator 里配置的模型通道可用。如果用的是 TaoToken检查 Key 是否有对应模型的调用权限。另外评估任务是异步执行的创建后需要等几分钟才能在 Score Analytics 里看到结果。ClickHouse 占用磁盘过大。trace 数据默认永久保留。可以在 Langfuse 的 Settings 里配置数据保留策略或者定期清理旧数据。本地开发环境可以直接docker compose down -v清空所有数据卷重新开始。SDK 上报延迟高。Langfuse SDK 默认批量异步上报如果希望实时看到 trace可以在初始化时设置flush_at1但会增加网络请求频率。生产环境建议保持默认的批量模式。整套流程跑通后你手里就有了一个完整的 LLM 可观测闭环模型调用走 TaoToken 统一通道trace 数据落到本地 Langfuse评估任务在 trace 上自动执行。后续要做的就是在业务代码里持续加observe()装饰器把更多环节纳入观测范围。