尧图网站建设 
这次我们来看一个面向大模型应用开发者的实战项目基于 Langfuse 平台的智能体评估与 LLM 观测。如果你正在开发或优化基于大语言模型LLM的智能体Agent、RAG 系统或复杂应用链并且苦于无法有效追踪每一次 API 调用、评估生成质量、调试复杂流程那么这个项目正是为你准备的。Langfuse 是一个开源的 LLM 应用观测与评估平台它不是一个模型而是一个强大的“仪表盘”和“分析工具”能帮你把黑盒的 AI 调用过程变得透明、可度量、可优化。它的核心价值在于将分散的日志、评估指标和用户反馈整合到一个统一的界面中让你能清晰地看到每次请求的输入输出是什么、调用了哪些模型、消耗了多少 Token、花费了多少钱、生成的答案质量如何、以及整个调用链的延迟和错误情况。对于追求稳定性和成本可控的生产级应用来说这种可观测性至关重要。本文将带你从零开始完成一个完整的智能体评估实战项目。我们会重点覆盖如何快速部署 Langfuse支持本地和云托管、如何将你的 LLM 应用代码与 Langfuse 集成、如何设计并自动化执行评估任务、以及如何利用追踪数据来调试和优化你的智能体。整个过程不涉及复杂的模型训练聚焦于工程化落地目标是让你看完就能动手搭建自己的 LLM 观测体系。1. 核心能力速览在深入细节之前我们先通过一个表格快速了解 Langfuse 的核心能力、技术门槛和适用场景帮助你判断是否值得投入时间。能力项具体说明项目类型LLM 应用可观测性 (Observability) 与评估 (Evaluation) 平台核心功能请求追踪 (Tracing)、日志记录、成本计算、自动化评估 (Scores Metrics)、生产监控、会话回放部署方式云托管 (SaaS)直接注册使用免运维。本地/自托管通过 Docker Compose 或二进制文件部署数据完全自主控制。硬件门槛云托管无要求有网络即可。本地部署推荐 2核 CPU / 4GB 内存以上主要用于运行 Web 服务和数据库不消耗 GPU 资源。集成复杂度低至中。提供 Python/JS/TS SDK通过装饰器或手动插桩的方式几行代码即可集成到现有应用中。是否支持 API是。提供完整的 REST API 用于数据查询、导出和批量操作。是否支持批量评估是。核心功能之一支持基于数据集 (Dataset) 的自动化批量测试与评分。数据存储自托管版使用 PostgreSQL 数据库所有追踪数据本地存储保障隐私与安全。适合场景1. 开发调试复杂的 LLM 应用链 (LangChain, LlamaIndex)。2. 对生产环境中的 AI 应用进行性能监控与成本分析。3. 构建自动化评估流水线量化智能体或 RAG 系统的效果。4. 收集用户反馈用于持续优化提示词 (Prompt) 和模型选择。从表格可以看出Langfuse 的门槛主要在于理解和集成其观测体系而非硬件算力。它更像一个“增强版的日志系统”专门为 AI 应用设计。2. 适用场景与使用边界理解一个工具适合做什么、不适合做什么比盲目上手更重要。Langfuse 最适合的三大场景智能体 (Agent) 与复杂工作流调试当一个用户问题需要经过多轮思考 (Reasoning)、工具调用 (Tool Calling) 和模型交互才能解决时整个调用链就像一团乱麻。Langfuse 可以可视化每一步的输入、输出、耗时和 Token 消耗让你快速定位是哪个环节的提示词出了问题还是某个工具调用超时。RAG 系统效果评估与优化检索增强生成 (RAG) 的质量取决于检索、排序和生成多个环节。通过 Langfuse你可以追踪每一次查询的检索结果、传递给模型的上下文、以及最终答案。结合自动化评估如答案相关性、事实准确性你能科学地评估不同检索策略、分块大小或重排模型的效果。生产环境监控与成本管控当你的应用服务大量用户时你需要知道哪个模型 API 调用最频繁每天消耗多少 Token成本是多少平均响应延迟是多少有没有异常的失败请求Langfuse 的仪表盘能直接给出这些洞察帮助你优化模型选型、设置预算告警。Langfuse 不擅长或需要谨慎使用的场景替代模型训练与微调Langfuse 用于观测和评估模型“使用”过程不提供模型训练能力。处理极端敏感数据虽然自托管版能保证数据不出私域但你仍需确保数据库和服务器本身的安全。对于医疗、金融等受严格监管的数据部署和访问控制需格外谨慎。替代单元测试它主要用于集成测试和线上监控不能完全替代针对业务逻辑的细粒度单元测试。合规与安全边界提醒数据隐私如果你使用云托管版需仔细阅读其数据协议确认传输和存储的数据是否符合你所在地区如 GDPR的要求。对于敏感业务数据强烈建议使用自托管版。用户知情权如果追踪的数据包含用户输入的隐私信息应考虑在前端告知用户并获得同意。授权使用确保你通过 Langfuse 观测的模型 API如 OpenAI, Anthropic是合法授权使用的遵守相关 API 的使用条款。3. 环境准备与前置条件我们将以本地 Docker 部署为例这是最通用、数据最可控的方式。如果你希望快速体验也可以直接注册其云服务跳过部署步骤。基础环境要求操作系统Linux (Ubuntu 20.04 / CentOS 7), macOS, 或 Windows 10/11 (需安装 WSL2 以获得最佳体验)。本文命令以 Linux/macOS 为例。Docker 与 Docker Compose这是运行 Langfuse 服务的核心。Docker确保已安装 Docker Engine。终端执行docker --version验证。Docker Compose确保已安装 Docker Compose V2。终端执行docker compose version验证。网络与端口确保主机本地机器的3000(前端) 和9020(后端) 端口未被占用。如果需要修改后续在配置文件中调整。磁盘空间预留至少 2GB 的可用空间用于存储 Docker 镜像和数据库数据。开发环境用于集成 SDKPython3.8 或更高版本。这是集成 Langfuse Python SDK 所必需的。Node.js16 或更高版本如果你使用 JS/TS SDK。环境检查清单在开始前请在终端依次运行以下命令确保基础环境就绪# 1. 检查 Docker docker --version # 预期输出类似Docker version 24.0.7, build afdd53b # 2. 检查 Docker Compose docker compose version # 预期输出类似Docker Compose version v2.23.0 # 3. 检查 Python python3 --version # 预期输出类似Python 3.10.12 # 4. 检查 3000 和 9020 端口占用 (Linux/macOS) sudo lsof -i :3000 sudo lsof -i :9020 # 如果无输出则表示端口空闲。4. 安装部署与启动方式我们将使用官方提供的docker-compose.yml文件来一键启动所有服务前端、后端、数据库。步骤 1获取部署文件在你想安装的目录下例如~/projects/langfuse执行以下命令# 创建项目目录并进入 mkdir -p ~/projects/langfuse cd ~/projects/langfuse # 下载官方 docker-compose 配置文件 curl -o docker-compose.yml https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml步骤 2启动 Langfuse 服务在包含docker-compose.yml文件的目录下运行# 使用 -d 参数在后台运行 docker compose up -d这个命令会拉取必要的镜像PostgreSQL, Langfuse 后端和前端并启动所有容器。第一次运行可能需要几分钟下载镜像。步骤 3验证服务状态启动完成后检查容器是否正常运行docker compose ps你应该看到三个服务langfuse-db,langfuse-server,langfuse-frontend的状态都是Up。步骤 4访问 Web 界面在浏览器中打开http://localhost:3000。如果一切正常你将看到 Langfuse 的注册页面。步骤 5创建初始账户在注册页面输入你的邮箱和密码创建第一个管理员账户。这个账户将用于登录和管理你的 Langfuse 实例。至此Langfuse 平台已经部署完成并可以访问。接下来我们需要将其与你的 LLM 应用连接起来。5. 功能测试与效果验证集成与追踪部署好平台只是第一步核心是让你的应用数据能流入 Langfuse。我们通过一个简单的 Python 示例来演示完整的集成、追踪和评估流程。5.1 准备测试应用环境首先在一个新的 Python 虚拟环境中安装必要的 SDK。# 创建并激活虚拟环境可选但推荐 python3 -m venv venv source venv/bin/activate # Windows 使用 venv\Scripts\activate # 安装 Langfuse Python SDK 和 OpenAI SDK用于模拟LLM调用 pip install langfuse openai5.2 配置 Langfuse 凭证登录 Langfuse Web 界面 (http://localhost:3000)。点击左下角个人头像进入“Settings”。在“API Keys”页面点击“Create new API key”。为其命名如test-key并复制生成的公钥 (Public Key)和私钥 (Secret Key)。页面关闭后将无法再次查看私钥请妥善保存。在你的 Python 代码或环境变量中配置这些凭证# 在终端中设置环境变量临时 export LANGFUSE_PUBLIC_KEYpk-lf-xxxxxx export LANGFUSE_SECRET_KEYsk-lf-xxxxxx export LANGFUSE_HOSThttp://localhost:3000 # 自托管地址5.3 基础追踪装饰器集成这是最简单的集成方式。假设我们有一个函数它调用 OpenAI API 来回答问题。# test_basic_trace.py import os from langfuse.decorators import observe, langfuse_context from openai import OpenAI # 初始化 OpenAI 客户端 (你需要有自己的 OPENAI_API_KEY) client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) observe() # 使用装饰器自动追踪此函数 def ask_ai(question: str): 一个简单的问答函数 print(f用户问题: {question}) # 调用 OpenAI API response client.chat.completions.create( modelgpt-3.5-turbo, messages[{role: user, content: question}], temperature0.7, ) answer response.choices[0].message.content print(fAI 回答: {answer}) # 你可以手动记录一些自定义信息到当前追踪中 langfuse_context.score_current_trace( nameuser_feedback, value5, # 假设我们模拟一个用户评分满分5分 comment模拟反馈回答准确 ) return answer if __name__ __main__: # 执行函数自动产生追踪记录 result ask_ai(Langfuse 是什么它主要解决什么问题)运行这个脚本后打开 Langfuse 的 Web 界面 (http://localhost:3000)进入“Traces”页面。你应该能看到一条新的追踪记录点击进入可以查看时间线函数执行的开始和结束时间。输入/输出question参数和函数的返回值。子步骤自动捕获的openai.chat.completions.create调用详情包括模型、Token 使用量、延迟。评分我们手动添加的user_feedback分数。5.4 复杂追踪手动插桩与智能体模拟对于更复杂的场景如 LangChain、LlamaIndex 或自定义的智能体流程可以使用手动插桩来获得更精细的控制。# test_agent_trace.py import os from langfuse import Langfuse from langfuse.callback import CallbackHandler import random # 初始化 Langfuse 客户端 langfuse Langfuse( public_keyos.getenv(LANGFUSE_PUBLIC_KEY), secret_keyos.getenv(LANGFUSE_SECRET_KEY), hostos.getenv(LANGFUSE_HOST), ) def simulate_web_search(query: str): 模拟一个网络搜索工具 return f关于 {query} 的搜索结果摘要...模拟数据 def simulate_calculator(expression: str): 模拟一个计算工具 return f计算结果{eval(expression)} # 注意生产环境勿用 eval def run_agent_workflow(user_query: str): 模拟一个简单的智能体工作流分析问题 - 选择工具 - 执行 - 总结 # 1. 创建主追踪 (Trace) trace langfuse.trace( nameAgent Workflow, inputuser_query, metadata{user_id: test_user_001} ) # 2. 第一步分析用户意图 (Span) analysis_span trace.span( nameIntent Analysis, inputuser_query, ) # 模拟分析逻辑 if 计算 in user_query or in user_query or * in user_query: tool_to_use calculator analysis_result 用户需要进行数学计算。 else: tool_to_use web_search analysis_result 用户需要查询信息。 analysis_span.end(outputanalysis_result) # 3. 第二步执行工具调用 (Span) tool_span trace.span( namefTool Execution: {tool_to_use}, input{tool: tool_to_use, query: user_query}, ) if tool_to_use calculator: # 简单提取计算表达式实际应用需要更复杂的解析 import re numbers re.findall(r\d, user_query) if len(numbers) 2: expr f{numbers[0]}{numbers[1]} tool_result simulate_calculator(expr) else: tool_result 无法解析计算表达式。 else: tool_result simulate_web_search(user_query) tool_span.end(outputtool_result) # 4. 第三步生成最终回答 (Span) generation_span trace.generation( nameFinal Answer Generation, modelsimulated-llm, model_parameters{temperature: 0.5}, input{analysis: analysis_result, tool_result: tool_result}, ) final_answer f根据分析{analysis_result}和工具执行结果我的回答是{tool_result} generation_span.end(outputfinal_answer) # 5. 结束主追踪并添加一个总体评分 trace.update(outputfinal_answer) langfuse.score( trace_idtrace.id, nameworkflow_quality, valuerandom.randint(3, 5), # 模拟一个随机评分 comment自动生成的模拟评分 ) print(f智能体最终回答: {final_answer}) return final_answer if __name__ __main__: queries [今天北京的天气怎么样, 请计算 25 乘以 38 等于多少] for q in queries: print(f\n处理查询: {q}) run_agent_workflow(q)运行此脚本后再次查看 Langfuse 的“Traces”页面。这次你会看到更复杂的追踪树一个主Trace包含三个Span分析、工具执行、生成。每个Span都有独立的输入、输出和耗时。最后关联了一个Score评分。这种细粒度的追踪是调试多步骤智能体的利器。6. 接口 API 与批量任务Langfuse 不仅提供 Web UI也提供了功能强大的 REST API允许你以编程方式管理数据、执行批量操作。6.1 核心 API 调用示例以下示例演示如何使用 Pythonrequests库调用 Langfuse API 来创建追踪和查询数据。# test_langfuse_api.py import requests import json import os # 配置 LANGFUSE_HOST os.getenv(LANGFUSE_HOST, http://localhost:3000) PUBLIC_KEY os.getenv(LANGFUSE_PUBLIC_KEY) SECRET_KEY os.getenv(LANGFUSE_SECRET_KEY) # API 基础路径 BASE_URL f{LANGFUSE_HOST}/api/public headers { Authorization: fBearer {SECRET_KEY}, Content-Type: application/json } def create_trace_via_api(): 通过 API 直接创建一条追踪记录 url f{BASE_URL}/traces payload { name: API-Created-Trace, input: {question: What is the capital of France?}, output: {answer: Paris}, metadata: {source: api_test}, sessionId: session_api_001 } response requests.post(url, jsonpayload, headersheaders) if response.status_code 200: trace_data response.json() print(f追踪创建成功Trace ID: {trace_data.get(id)}) return trace_data.get(id) else: print(f创建失败: {response.status_code}, {response.text}) return None def get_traces(): 查询最近的追踪记录 url f{BASE_URL}/traces params {limit: 5} response requests.get(url, paramsparams, headersheaders) if response.status_code 200: traces response.json().get(data, []) print(f获取到 {len(traces)} 条追踪:) for t in traces: print(f - {t.get(name)} (ID: {t.get(id)})) else: print(f查询失败: {response.status_code}) def create_dataset_and_run_evaluation(): 演示如何创建数据集并关联评估概念性步骤 # 1. 创建数据集 dataset_payload { name: Customer_Service_QA, description: 用于评估客服机器人效果的数据集 } # 2. 向数据集中添加样本这里需要具体的 item 结构请参考官方API文档 # 3. 执行批量评估通常需要结合 SDK 或自定义脚本循环处理数据集中的每个样本 print(批量评估流程涉及多个API调用建议结合SDK或查看官方文档。) if __name__ __main__: trace_id create_trace_via_api() if trace_id: # 可以基于 trace_id 进行评分等后续操作 pass get_traces()6.2 批量评估任务设计批量评估是 Langfuse 的核心优势。典型流程如下创建数据集 (Dataset)在 Langfuse UI 中或通过 API创建一个数据集并上传一批测试用例例如{“input”: “用户问题”, “expected_output”: “期望答案”}。编写评估函数 (Evaluation Function)定义一个 Python 函数它接受一个测试用例调用你的 LLM 应用并返回一个或多个评分如正确性、相关性、流畅度。这个函数内部应使用 Langfuse SDK 进行追踪。执行批量运行遍历数据集中的所有项目对每个项目执行评估函数。Langfuse 会自动为每次运行创建追踪并将结果与数据集项目关联。分析与比较在 Langfuse UI 的 “Dataset” 页面你可以看到所有测试用例的运行结果、评分对比。你可以快速识别出哪些问题你的应用处理得不好从而针对性优化。这种模式将评估从一次性、手动的活动转变为可重复、可量化的自动化流程。7. 资源占用与性能观察由于 Langfuse 本身不运行大模型其资源消耗主要来自 Web 服务、后端处理和数据库。自托管版资源占用观察启动 Langfuse 服务后你可以使用docker stats命令来查看容器资源使用情况docker stats --no-stream在典型的小规模开发或测试场景下日追踪量在万条以内你可能会观察到CPU三个容器合计占用约 1-5%大部分时间空闲。内存langfuse-server和langfuse-frontend各占用约 200-500 MBlangfuse-db(PostgreSQL) 占用约 100-300 MB。总计约 1GB 左右。磁盘镜像本身约 1GB。数据库增长取决于你存储的追踪数据量。每条追踪记录包含所有 Spans, Generations根据复杂度可能占用几 KB 到几十 KB。性能影响因素SDK 集成模式使用observe装饰器或CallbackHandler对应用本身的性能影响极低微秒级。手动插桩的trace/span调用也主要是网络 I/O。网络延迟SDK 默认是异步发送数据到 Langfuse 后端不会阻塞你的主应用线程。但如果后端地址 (LANGFUSE_HOST) 网络不通或延迟很高可能会在后台线程中产生错误或重试不影响主流程但可能丢失数据。数据库压力如果产生海量追踪数据例如每秒上千条PostgreSQL 可能成为瓶颈。建议定期清理旧数据或升级数据库配置。前端响应当单次查询需要渲染成千上万条追踪时Web 界面可能会变慢。合理使用过滤器和分页。优化建议生产环境部署考虑将langfuse-db的数据卷挂载到高性能 SSD 上。数据保留策略在设置中配置自动删除旧追踪数据如保留 30 天或定期手动清理。监控 Langfuse 自身可以为你的 Langfuse 服务也设置基础监控如容器健康检查、日志收集。8. 常见问题与排查方法在部署和使用过程中你可能会遇到以下问题。这里提供系统的排查思路。问题现象可能原因排查方式解决方案访问localhost:3000失败1. 容器未成功启动。2. 端口被其他程序占用。3. 防火墙/安全组阻止。1.docker compose ps查看容器状态。2.docker compose logs查看启动日志。3.netstat -tuln | grep :3000检查端口。1. 根据日志修复错误常见如数据库连接失败。2. 修改docker-compose.yml中的端口映射如3001:3000。3. 配置防火墙规则或关闭冲突程序。SDK 集成后数据未出现在 UI1. 凭证 (API Keys) 错误。2.LANGFUSE_HOST配置错误。3. SDK 初始化或调用代码有误。4. 网络问题导致数据发送失败。1. 检查环境变量或代码中的公钥/私钥/主机地址。2. 在代码中捕获并打印 Langfuse 初始化或调用异常。3. 检查浏览器开发者工具 Network 面板看是否有向/api/public/ingestion发送请求。1. 重新生成 API Key 并确认。2. 自托管时LANGFUSE_HOST必须是后端地址默认http://localhost:3000。3. 确保langfuse.flush()被调用SDK 异步发送程序退出前需刷新缓冲区。追踪数据延迟显示SDK 默认采用异步批量发送机制有延迟通常几秒到一分钟。等待片刻再刷新 UI。1. 对于测试可以调用langfuse.flush()强制立即发送。2. 调整 SDK 的flush_interval参数以秒为单位。数据库磁盘空间增长过快1. 产生大量追踪数据且未清理。2. 数据库日志未清理。1. 在 Langfuse UI 的 “Project Settings” 中查看数据量统计。2. 进入数据库容器检查表大小。1. 在设置中启用数据保留策略自动删除旧数据。2. 定期手动执行清理 SQL需谨慎。3. 考虑只追踪关键路径减少冗余数据。“Generation” 步骤未记录 Token 用量使用的 LLM SDK如openai版本与 Langfuse 回调不兼容或未正确集成。检查追踪详情中 Generation 步骤的元数据是否包含model,usage字段。1. 确保使用 Langfuse 的CallbackHandler与 LangChain/LlamaIndex 集成。2. 对于原生 OpenAI SDK使用observe装饰器或手动trace.generation()记录。批量评估时评分未关联到数据集评估函数中未正确使用dataset_item_id或session_id进行关联。检查批量评估脚本确保在创建 Trace 时传入了dataset_item_id参数。参考官方批量评估示例确保数据流关联正确。通常需要在处理每个数据集项时将项 ID 传递给追踪。通用排查命令# 查看 Langfuse 容器日志 docker compose logs -f langfuse-server docker compose logs -f langfuse-frontend # 重启所有服务 docker compose down docker compose up -d # 进入数据库容器执行查询高级 docker compose exec langfuse-db psql -U postgres -d postgres9. 最佳实践与使用建议为了让 Langfuse 发挥最大价值并避免常见陷阱遵循以下最佳实践从关键路径开始逐步扩大追踪范围不要一开始就在所有函数上加装饰器。先在你的核心 LLM 调用链或最复杂的智能体流程上集成看到价值后再逐步扩展到其他部分。为追踪和会话 (Session) 设置清晰的标识利用trace_id,session_id,user_id等字段。这能让你在 UI 中轻松过滤和查询特定用户或会话的所有交互对于分析用户体验至关重要。善用元数据 (Metadata) 和标签 (Tags)在创建 Trace 或 Span 时添加有业务意义的元数据如{“environment”: “staging”, “app_version”: “1.2.0”, “feature_flag”: “new_prompt”}。这让你能对比不同版本或配置下的应用表现。设计有意义的评估指标 (Scores)不要只用一个“好坏”评分。针对你的场景设计多维度的评估体系。例如事实准确性针对 RAG 系统评估答案是否基于提供的上下文且事实正确。相关性答案是否直接回答了问题。有害性内容是否安全。风格符合度语气、格式是否符合要求。成本与延迟作为客观指标进行监控。建立自动化评估流水线将你的测试数据集和评估函数脚本化并集成到 CI/CD 流程中。每次代码或提示词更新后自动运行评估对比关键指标的变化防止回归。定期审查生产环境追踪每周或每月抽检一些生产环境的失败或低分追踪。这能帮你发现意料之外的模型行为、边缘案例或提示词缺陷。注意数据安全与合规自托管保障数据主权对数据敏感的项目始终选择自托管。避免记录敏感信息在 SDK 中配置redacted_keys自动脱敏追踪中的密码、密钥等字段。设置访问控制利用 Langfuse 的项目和成员管理功能控制团队成员的数据访问权限。10. 总结与下一步Langfuse 将一个复杂的工程问题——LLM 应用的可观测性与评估——变成了一个可以系统化解决的方案。通过本次实战你应该已经掌握了从零部署、集成 SDK、进行复杂追踪到设计批量评估的完整流程。最值得尝试的下一步将你现有的一个 LangChain 或 LlamaIndex 项目集成 Langfuse使用CallbackHandler这是集成最快的方式。亲眼看看一个 RAG 问答的完整检索、生成链条被可视化出来你会立刻感受到它的价值。创建一个包含 20-30 个问题的测试数据集涵盖你应用的典型用例和常见失败案例。运行一次批量评估找出当前系统的薄弱环节。探索生产监控如果你有线上应用以低采样率例如 1%开启 Langfuse 追踪监控 API 成本、延迟和错误率。设置简单的告警如成本日环比增长超 20%。最容易踩的坑忽略异步发送机制在短时运行的脚本中数据可能因程序提前退出而丢失记得调用flush()。混淆 Host 地址自托管时SDK 配置的host是 Langfuse 后端地址如http://localhost:3000而不是前端地址。过度追踪追踪所有细节会产生大量数据可能拖慢 UI 并增加存储成本。聚焦于核心业务逻辑。将这个平台作为你 LLM 应用开发的“仪表盘”持续观察、测量、实验和优化。当你能清晰地看到每一次调用、每一分成本、每一个评分时优化方向就不再是猜测而是数据驱动的决策。建议收藏本文在集成和排查时作为参考。 基于Langfuse的LLM应用可观测性实战：从部署到智能体评估
这次我们来看一个面向大模型应用开发者的实战项目基于 Langfuse 平台的智能体评估与 LLM 观测。如果你正在开发或优化基于大语言模型LLM的智能体Agent、RAG 系统或复杂应用链并且苦于无法有效追踪每一次 API 调用、评估生成质量、调试复杂流程那么这个项目正是为你准备的。Langfuse 是一个开源的 LLM 应用观测与评估平台它不是一个模型而是一个强大的“仪表盘”和“分析工具”能帮你把黑盒的 AI 调用过程变得透明、可度量、可优化。它的核心价值在于将分散的日志、评估指标和用户反馈整合到一个统一的界面中让你能清晰地看到每次请求的输入输出是什么、调用了哪些模型、消耗了多少 Token、花费了多少钱、生成的答案质量如何、以及整个调用链的延迟和错误情况。对于追求稳定性和成本可控的生产级应用来说这种可观测性至关重要。本文将带你从零开始完成一个完整的智能体评估实战项目。我们会重点覆盖如何快速部署 Langfuse支持本地和云托管、如何将你的 LLM 应用代码与 Langfuse 集成、如何设计并自动化执行评估任务、以及如何利用追踪数据来调试和优化你的智能体。整个过程不涉及复杂的模型训练聚焦于工程化落地目标是让你看完就能动手搭建自己的 LLM 观测体系。1. 核心能力速览在深入细节之前我们先通过一个表格快速了解 Langfuse 的核心能力、技术门槛和适用场景帮助你判断是否值得投入时间。能力项具体说明项目类型LLM 应用可观测性 (Observability) 与评估 (Evaluation) 平台核心功能请求追踪 (Tracing)、日志记录、成本计算、自动化评估 (Scores Metrics)、生产监控、会话回放部署方式云托管 (SaaS)直接注册使用免运维。本地/自托管通过 Docker Compose 或二进制文件部署数据完全自主控制。硬件门槛云托管无要求有网络即可。本地部署推荐 2核 CPU / 4GB 内存以上主要用于运行 Web 服务和数据库不消耗 GPU 资源。集成复杂度低至中。提供 Python/JS/TS SDK通过装饰器或手动插桩的方式几行代码即可集成到现有应用中。是否支持 API是。提供完整的 REST API 用于数据查询、导出和批量操作。是否支持批量评估是。核心功能之一支持基于数据集 (Dataset) 的自动化批量测试与评分。数据存储自托管版使用 PostgreSQL 数据库所有追踪数据本地存储保障隐私与安全。适合场景1. 开发调试复杂的 LLM 应用链 (LangChain, LlamaIndex)。2. 对生产环境中的 AI 应用进行性能监控与成本分析。3. 构建自动化评估流水线量化智能体或 RAG 系统的效果。4. 收集用户反馈用于持续优化提示词 (Prompt) 和模型选择。从表格可以看出Langfuse 的门槛主要在于理解和集成其观测体系而非硬件算力。它更像一个“增强版的日志系统”专门为 AI 应用设计。2. 适用场景与使用边界理解一个工具适合做什么、不适合做什么比盲目上手更重要。Langfuse 最适合的三大场景智能体 (Agent) 与复杂工作流调试当一个用户问题需要经过多轮思考 (Reasoning)、工具调用 (Tool Calling) 和模型交互才能解决时整个调用链就像一团乱麻。Langfuse 可以可视化每一步的输入、输出、耗时和 Token 消耗让你快速定位是哪个环节的提示词出了问题还是某个工具调用超时。RAG 系统效果评估与优化检索增强生成 (RAG) 的质量取决于检索、排序和生成多个环节。通过 Langfuse你可以追踪每一次查询的检索结果、传递给模型的上下文、以及最终答案。结合自动化评估如答案相关性、事实准确性你能科学地评估不同检索策略、分块大小或重排模型的效果。生产环境监控与成本管控当你的应用服务大量用户时你需要知道哪个模型 API 调用最频繁每天消耗多少 Token成本是多少平均响应延迟是多少有没有异常的失败请求Langfuse 的仪表盘能直接给出这些洞察帮助你优化模型选型、设置预算告警。Langfuse 不擅长或需要谨慎使用的场景替代模型训练与微调Langfuse 用于观测和评估模型“使用”过程不提供模型训练能力。处理极端敏感数据虽然自托管版能保证数据不出私域但你仍需确保数据库和服务器本身的安全。对于医疗、金融等受严格监管的数据部署和访问控制需格外谨慎。替代单元测试它主要用于集成测试和线上监控不能完全替代针对业务逻辑的细粒度单元测试。合规与安全边界提醒数据隐私如果你使用云托管版需仔细阅读其数据协议确认传输和存储的数据是否符合你所在地区如 GDPR的要求。对于敏感业务数据强烈建议使用自托管版。用户知情权如果追踪的数据包含用户输入的隐私信息应考虑在前端告知用户并获得同意。授权使用确保你通过 Langfuse 观测的模型 API如 OpenAI, Anthropic是合法授权使用的遵守相关 API 的使用条款。3. 环境准备与前置条件我们将以本地 Docker 部署为例这是最通用、数据最可控的方式。如果你希望快速体验也可以直接注册其云服务跳过部署步骤。基础环境要求操作系统Linux (Ubuntu 20.04 / CentOS 7), macOS, 或 Windows 10/11 (需安装 WSL2 以获得最佳体验)。本文命令以 Linux/macOS 为例。Docker 与 Docker Compose这是运行 Langfuse 服务的核心。Docker确保已安装 Docker Engine。终端执行docker --version验证。Docker Compose确保已安装 Docker Compose V2。终端执行docker compose version验证。网络与端口确保主机本地机器的3000(前端) 和9020(后端) 端口未被占用。如果需要修改后续在配置文件中调整。磁盘空间预留至少 2GB 的可用空间用于存储 Docker 镜像和数据库数据。开发环境用于集成 SDKPython3.8 或更高版本。这是集成 Langfuse Python SDK 所必需的。Node.js16 或更高版本如果你使用 JS/TS SDK。环境检查清单在开始前请在终端依次运行以下命令确保基础环境就绪# 1. 检查 Docker docker --version # 预期输出类似Docker version 24.0.7, build afdd53b # 2. 检查 Docker Compose docker compose version # 预期输出类似Docker Compose version v2.23.0 # 3. 检查 Python python3 --version # 预期输出类似Python 3.10.12 # 4. 检查 3000 和 9020 端口占用 (Linux/macOS) sudo lsof -i :3000 sudo lsof -i :9020 # 如果无输出则表示端口空闲。4. 安装部署与启动方式我们将使用官方提供的docker-compose.yml文件来一键启动所有服务前端、后端、数据库。步骤 1获取部署文件在你想安装的目录下例如~/projects/langfuse执行以下命令# 创建项目目录并进入 mkdir -p ~/projects/langfuse cd ~/projects/langfuse # 下载官方 docker-compose 配置文件 curl -o docker-compose.yml https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml步骤 2启动 Langfuse 服务在包含docker-compose.yml文件的目录下运行# 使用 -d 参数在后台运行 docker compose up -d这个命令会拉取必要的镜像PostgreSQL, Langfuse 后端和前端并启动所有容器。第一次运行可能需要几分钟下载镜像。步骤 3验证服务状态启动完成后检查容器是否正常运行docker compose ps你应该看到三个服务langfuse-db,langfuse-server,langfuse-frontend的状态都是Up。步骤 4访问 Web 界面在浏览器中打开http://localhost:3000。如果一切正常你将看到 Langfuse 的注册页面。步骤 5创建初始账户在注册页面输入你的邮箱和密码创建第一个管理员账户。这个账户将用于登录和管理你的 Langfuse 实例。至此Langfuse 平台已经部署完成并可以访问。接下来我们需要将其与你的 LLM 应用连接起来。5. 功能测试与效果验证集成与追踪部署好平台只是第一步核心是让你的应用数据能流入 Langfuse。我们通过一个简单的 Python 示例来演示完整的集成、追踪和评估流程。5.1 准备测试应用环境首先在一个新的 Python 虚拟环境中安装必要的 SDK。# 创建并激活虚拟环境可选但推荐 python3 -m venv venv source venv/bin/activate # Windows 使用 venv\Scripts\activate # 安装 Langfuse Python SDK 和 OpenAI SDK用于模拟LLM调用 pip install langfuse openai5.2 配置 Langfuse 凭证登录 Langfuse Web 界面 (http://localhost:3000)。点击左下角个人头像进入“Settings”。在“API Keys”页面点击“Create new API key”。为其命名如test-key并复制生成的公钥 (Public Key)和私钥 (Secret Key)。页面关闭后将无法再次查看私钥请妥善保存。在你的 Python 代码或环境变量中配置这些凭证# 在终端中设置环境变量临时 export LANGFUSE_PUBLIC_KEYpk-lf-xxxxxx export LANGFUSE_SECRET_KEYsk-lf-xxxxxx export LANGFUSE_HOSThttp://localhost:3000 # 自托管地址5.3 基础追踪装饰器集成这是最简单的集成方式。假设我们有一个函数它调用 OpenAI API 来回答问题。# test_basic_trace.py import os from langfuse.decorators import observe, langfuse_context from openai import OpenAI # 初始化 OpenAI 客户端 (你需要有自己的 OPENAI_API_KEY) client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) observe() # 使用装饰器自动追踪此函数 def ask_ai(question: str): 一个简单的问答函数 print(f用户问题: {question}) # 调用 OpenAI API response client.chat.completions.create( modelgpt-3.5-turbo, messages[{role: user, content: question}], temperature0.7, ) answer response.choices[0].message.content print(fAI 回答: {answer}) # 你可以手动记录一些自定义信息到当前追踪中 langfuse_context.score_current_trace( nameuser_feedback, value5, # 假设我们模拟一个用户评分满分5分 comment模拟反馈回答准确 ) return answer if __name__ __main__: # 执行函数自动产生追踪记录 result ask_ai(Langfuse 是什么它主要解决什么问题)运行这个脚本后打开 Langfuse 的 Web 界面 (http://localhost:3000)进入“Traces”页面。你应该能看到一条新的追踪记录点击进入可以查看时间线函数执行的开始和结束时间。输入/输出question参数和函数的返回值。子步骤自动捕获的openai.chat.completions.create调用详情包括模型、Token 使用量、延迟。评分我们手动添加的user_feedback分数。5.4 复杂追踪手动插桩与智能体模拟对于更复杂的场景如 LangChain、LlamaIndex 或自定义的智能体流程可以使用手动插桩来获得更精细的控制。# test_agent_trace.py import os from langfuse import Langfuse from langfuse.callback import CallbackHandler import random # 初始化 Langfuse 客户端 langfuse Langfuse( public_keyos.getenv(LANGFUSE_PUBLIC_KEY), secret_keyos.getenv(LANGFUSE_SECRET_KEY), hostos.getenv(LANGFUSE_HOST), ) def simulate_web_search(query: str): 模拟一个网络搜索工具 return f关于 {query} 的搜索结果摘要...模拟数据 def simulate_calculator(expression: str): 模拟一个计算工具 return f计算结果{eval(expression)} # 注意生产环境勿用 eval def run_agent_workflow(user_query: str): 模拟一个简单的智能体工作流分析问题 - 选择工具 - 执行 - 总结 # 1. 创建主追踪 (Trace) trace langfuse.trace( nameAgent Workflow, inputuser_query, metadata{user_id: test_user_001} ) # 2. 第一步分析用户意图 (Span) analysis_span trace.span( nameIntent Analysis, inputuser_query, ) # 模拟分析逻辑 if 计算 in user_query or in user_query or * in user_query: tool_to_use calculator analysis_result 用户需要进行数学计算。 else: tool_to_use web_search analysis_result 用户需要查询信息。 analysis_span.end(outputanalysis_result) # 3. 第二步执行工具调用 (Span) tool_span trace.span( namefTool Execution: {tool_to_use}, input{tool: tool_to_use, query: user_query}, ) if tool_to_use calculator: # 简单提取计算表达式实际应用需要更复杂的解析 import re numbers re.findall(r\d, user_query) if len(numbers) 2: expr f{numbers[0]}{numbers[1]} tool_result simulate_calculator(expr) else: tool_result 无法解析计算表达式。 else: tool_result simulate_web_search(user_query) tool_span.end(outputtool_result) # 4. 第三步生成最终回答 (Span) generation_span trace.generation( nameFinal Answer Generation, modelsimulated-llm, model_parameters{temperature: 0.5}, input{analysis: analysis_result, tool_result: tool_result}, ) final_answer f根据分析{analysis_result}和工具执行结果我的回答是{tool_result} generation_span.end(outputfinal_answer) # 5. 结束主追踪并添加一个总体评分 trace.update(outputfinal_answer) langfuse.score( trace_idtrace.id, nameworkflow_quality, valuerandom.randint(3, 5), # 模拟一个随机评分 comment自动生成的模拟评分 ) print(f智能体最终回答: {final_answer}) return final_answer if __name__ __main__: queries [今天北京的天气怎么样, 请计算 25 乘以 38 等于多少] for q in queries: print(f\n处理查询: {q}) run_agent_workflow(q)运行此脚本后再次查看 Langfuse 的“Traces”页面。这次你会看到更复杂的追踪树一个主Trace包含三个Span分析、工具执行、生成。每个Span都有独立的输入、输出和耗时。最后关联了一个Score评分。这种细粒度的追踪是调试多步骤智能体的利器。6. 接口 API 与批量任务Langfuse 不仅提供 Web UI也提供了功能强大的 REST API允许你以编程方式管理数据、执行批量操作。6.1 核心 API 调用示例以下示例演示如何使用 Pythonrequests库调用 Langfuse API 来创建追踪和查询数据。# test_langfuse_api.py import requests import json import os # 配置 LANGFUSE_HOST os.getenv(LANGFUSE_HOST, http://localhost:3000) PUBLIC_KEY os.getenv(LANGFUSE_PUBLIC_KEY) SECRET_KEY os.getenv(LANGFUSE_SECRET_KEY) # API 基础路径 BASE_URL f{LANGFUSE_HOST}/api/public headers { Authorization: fBearer {SECRET_KEY}, Content-Type: application/json } def create_trace_via_api(): 通过 API 直接创建一条追踪记录 url f{BASE_URL}/traces payload { name: API-Created-Trace, input: {question: What is the capital of France?}, output: {answer: Paris}, metadata: {source: api_test}, sessionId: session_api_001 } response requests.post(url, jsonpayload, headersheaders) if response.status_code 200: trace_data response.json() print(f追踪创建成功Trace ID: {trace_data.get(id)}) return trace_data.get(id) else: print(f创建失败: {response.status_code}, {response.text}) return None def get_traces(): 查询最近的追踪记录 url f{BASE_URL}/traces params {limit: 5} response requests.get(url, paramsparams, headersheaders) if response.status_code 200: traces response.json().get(data, []) print(f获取到 {len(traces)} 条追踪:) for t in traces: print(f - {t.get(name)} (ID: {t.get(id)})) else: print(f查询失败: {response.status_code}) def create_dataset_and_run_evaluation(): 演示如何创建数据集并关联评估概念性步骤 # 1. 创建数据集 dataset_payload { name: Customer_Service_QA, description: 用于评估客服机器人效果的数据集 } # 2. 向数据集中添加样本这里需要具体的 item 结构请参考官方API文档 # 3. 执行批量评估通常需要结合 SDK 或自定义脚本循环处理数据集中的每个样本 print(批量评估流程涉及多个API调用建议结合SDK或查看官方文档。) if __name__ __main__: trace_id create_trace_via_api() if trace_id: # 可以基于 trace_id 进行评分等后续操作 pass get_traces()6.2 批量评估任务设计批量评估是 Langfuse 的核心优势。典型流程如下创建数据集 (Dataset)在 Langfuse UI 中或通过 API创建一个数据集并上传一批测试用例例如{“input”: “用户问题”, “expected_output”: “期望答案”}。编写评估函数 (Evaluation Function)定义一个 Python 函数它接受一个测试用例调用你的 LLM 应用并返回一个或多个评分如正确性、相关性、流畅度。这个函数内部应使用 Langfuse SDK 进行追踪。执行批量运行遍历数据集中的所有项目对每个项目执行评估函数。Langfuse 会自动为每次运行创建追踪并将结果与数据集项目关联。分析与比较在 Langfuse UI 的 “Dataset” 页面你可以看到所有测试用例的运行结果、评分对比。你可以快速识别出哪些问题你的应用处理得不好从而针对性优化。这种模式将评估从一次性、手动的活动转变为可重复、可量化的自动化流程。7. 资源占用与性能观察由于 Langfuse 本身不运行大模型其资源消耗主要来自 Web 服务、后端处理和数据库。自托管版资源占用观察启动 Langfuse 服务后你可以使用docker stats命令来查看容器资源使用情况docker stats --no-stream在典型的小规模开发或测试场景下日追踪量在万条以内你可能会观察到CPU三个容器合计占用约 1-5%大部分时间空闲。内存langfuse-server和langfuse-frontend各占用约 200-500 MBlangfuse-db(PostgreSQL) 占用约 100-300 MB。总计约 1GB 左右。磁盘镜像本身约 1GB。数据库增长取决于你存储的追踪数据量。每条追踪记录包含所有 Spans, Generations根据复杂度可能占用几 KB 到几十 KB。性能影响因素SDK 集成模式使用observe装饰器或CallbackHandler对应用本身的性能影响极低微秒级。手动插桩的trace/span调用也主要是网络 I/O。网络延迟SDK 默认是异步发送数据到 Langfuse 后端不会阻塞你的主应用线程。但如果后端地址 (LANGFUSE_HOST) 网络不通或延迟很高可能会在后台线程中产生错误或重试不影响主流程但可能丢失数据。数据库压力如果产生海量追踪数据例如每秒上千条PostgreSQL 可能成为瓶颈。建议定期清理旧数据或升级数据库配置。前端响应当单次查询需要渲染成千上万条追踪时Web 界面可能会变慢。合理使用过滤器和分页。优化建议生产环境部署考虑将langfuse-db的数据卷挂载到高性能 SSD 上。数据保留策略在设置中配置自动删除旧追踪数据如保留 30 天或定期手动清理。监控 Langfuse 自身可以为你的 Langfuse 服务也设置基础监控如容器健康检查、日志收集。8. 常见问题与排查方法在部署和使用过程中你可能会遇到以下问题。这里提供系统的排查思路。问题现象可能原因排查方式解决方案访问localhost:3000失败1. 容器未成功启动。2. 端口被其他程序占用。3. 防火墙/安全组阻止。1.docker compose ps查看容器状态。2.docker compose logs查看启动日志。3.netstat -tuln | grep :3000检查端口。1. 根据日志修复错误常见如数据库连接失败。2. 修改docker-compose.yml中的端口映射如3001:3000。3. 配置防火墙规则或关闭冲突程序。SDK 集成后数据未出现在 UI1. 凭证 (API Keys) 错误。2.LANGFUSE_HOST配置错误。3. SDK 初始化或调用代码有误。4. 网络问题导致数据发送失败。1. 检查环境变量或代码中的公钥/私钥/主机地址。2. 在代码中捕获并打印 Langfuse 初始化或调用异常。3. 检查浏览器开发者工具 Network 面板看是否有向/api/public/ingestion发送请求。1. 重新生成 API Key 并确认。2. 自托管时LANGFUSE_HOST必须是后端地址默认http://localhost:3000。3. 确保langfuse.flush()被调用SDK 异步发送程序退出前需刷新缓冲区。追踪数据延迟显示SDK 默认采用异步批量发送机制有延迟通常几秒到一分钟。等待片刻再刷新 UI。1. 对于测试可以调用langfuse.flush()强制立即发送。2. 调整 SDK 的flush_interval参数以秒为单位。数据库磁盘空间增长过快1. 产生大量追踪数据且未清理。2. 数据库日志未清理。1. 在 Langfuse UI 的 “Project Settings” 中查看数据量统计。2. 进入数据库容器检查表大小。1. 在设置中启用数据保留策略自动删除旧数据。2. 定期手动执行清理 SQL需谨慎。3. 考虑只追踪关键路径减少冗余数据。“Generation” 步骤未记录 Token 用量使用的 LLM SDK如openai版本与 Langfuse 回调不兼容或未正确集成。检查追踪详情中 Generation 步骤的元数据是否包含model,usage字段。1. 确保使用 Langfuse 的CallbackHandler与 LangChain/LlamaIndex 集成。2. 对于原生 OpenAI SDK使用observe装饰器或手动trace.generation()记录。批量评估时评分未关联到数据集评估函数中未正确使用dataset_item_id或session_id进行关联。检查批量评估脚本确保在创建 Trace 时传入了dataset_item_id参数。参考官方批量评估示例确保数据流关联正确。通常需要在处理每个数据集项时将项 ID 传递给追踪。通用排查命令# 查看 Langfuse 容器日志 docker compose logs -f langfuse-server docker compose logs -f langfuse-frontend # 重启所有服务 docker compose down docker compose up -d # 进入数据库容器执行查询高级 docker compose exec langfuse-db psql -U postgres -d postgres9. 最佳实践与使用建议为了让 Langfuse 发挥最大价值并避免常见陷阱遵循以下最佳实践从关键路径开始逐步扩大追踪范围不要一开始就在所有函数上加装饰器。先在你的核心 LLM 调用链或最复杂的智能体流程上集成看到价值后再逐步扩展到其他部分。为追踪和会话 (Session) 设置清晰的标识利用trace_id,session_id,user_id等字段。这能让你在 UI 中轻松过滤和查询特定用户或会话的所有交互对于分析用户体验至关重要。善用元数据 (Metadata) 和标签 (Tags)在创建 Trace 或 Span 时添加有业务意义的元数据如{“environment”: “staging”, “app_version”: “1.2.0”, “feature_flag”: “new_prompt”}。这让你能对比不同版本或配置下的应用表现。设计有意义的评估指标 (Scores)不要只用一个“好坏”评分。针对你的场景设计多维度的评估体系。例如事实准确性针对 RAG 系统评估答案是否基于提供的上下文且事实正确。相关性答案是否直接回答了问题。有害性内容是否安全。风格符合度语气、格式是否符合要求。成本与延迟作为客观指标进行监控。建立自动化评估流水线将你的测试数据集和评估函数脚本化并集成到 CI/CD 流程中。每次代码或提示词更新后自动运行评估对比关键指标的变化防止回归。定期审查生产环境追踪每周或每月抽检一些生产环境的失败或低分追踪。这能帮你发现意料之外的模型行为、边缘案例或提示词缺陷。注意数据安全与合规自托管保障数据主权对数据敏感的项目始终选择自托管。避免记录敏感信息在 SDK 中配置redacted_keys自动脱敏追踪中的密码、密钥等字段。设置访问控制利用 Langfuse 的项目和成员管理功能控制团队成员的数据访问权限。10. 总结与下一步Langfuse 将一个复杂的工程问题——LLM 应用的可观测性与评估——变成了一个可以系统化解决的方案。通过本次实战你应该已经掌握了从零部署、集成 SDK、进行复杂追踪到设计批量评估的完整流程。最值得尝试的下一步将你现有的一个 LangChain 或 LlamaIndex 项目集成 Langfuse使用CallbackHandler这是集成最快的方式。亲眼看看一个 RAG 问答的完整检索、生成链条被可视化出来你会立刻感受到它的价值。创建一个包含 20-30 个问题的测试数据集涵盖你应用的典型用例和常见失败案例。运行一次批量评估找出当前系统的薄弱环节。探索生产监控如果你有线上应用以低采样率例如 1%开启 Langfuse 追踪监控 API 成本、延迟和错误率。设置简单的告警如成本日环比增长超 20%。最容易踩的坑忽略异步发送机制在短时运行的脚本中数据可能因程序提前退出而丢失记得调用flush()。混淆 Host 地址自托管时SDK 配置的host是 Langfuse 后端地址如http://localhost:3000而不是前端地址。过度追踪追踪所有细节会产生大量数据可能拖慢 UI 并增加存储成本。聚焦于核心业务逻辑。将这个平台作为你 LLM 应用开发的“仪表盘”持续观察、测量、实验和优化。当你能清晰地看到每一次调用、每一分成本、每一个评分时优化方向就不再是猜测而是数据驱动的决策。建议收藏本文在集成和排查时作为参考。