如果你正在开发或使用大语言模型LLM应用那么“模型表现不稳定”、“调试黑盒”、“成本不可控”这些问题大概率已经让你头疼不已。Langfuse 就是为解决这些痛点而生的开源可观测性平台它专为 LLM 应用设计能帮你追踪每一次调用、分析每一次成本、调试每一次异常。简单说它就像给 LLM 应用装上了“行车记录仪”和“性能分析仪”。这篇文章不空谈概念直接带你从零开始完成 Langfuse 最新版的本地部署、配置并接入一个示例项目。你会看到如何一键启动服务、如何通过几行代码集成 SDK、以及如何利用其强大的 Dashboard 进行追踪和调试。无论你是想监控自己开发的 AI 应用还是想优化基于 OpenAI、Anthropic 等服务的调用这套方案都能让你快速获得可见性。1. 核心能力速览在动手之前先快速了解 Langfuse 能做什么以及你需要准备什么。能力项说明项目类型开源 LLM 应用可观测性Observability平台核心功能追踪Tracing、日志Logging、评估Evaluation、数据标注Dataset Prompt Management部署方式支持 Docker Compose 一键部署推荐也支持云托管Langfuse Cloud数据存储使用 PostgreSQL 作为主数据库可选集成 ClickHouse 用于分析硬件门槛本地部署对显存无要求。主要消耗内存和 CPU 资源建议 4GB 内存。启动方式通过docker-compose up -d命令一键启动所有服务Web、Server、Worker。接口能力提供 RESTful API 和多种语言的 SDKPython、JS/TS、Java等便于项目集成。监控维度追踪链式调用、记录输入输出、计算 Token 使用与成本、分析延迟、进行人工或自动评估。适合场景开发调试 LLM 应用、生产环境监控与告警、分析用量与成本优化、管理提示词版本。简单来说你可以把它看作一个自托管的“增强版日志系统”专门为 AI 应用的复杂链式调用Chain/Trace设计提供了开箱即用的可视化界面。2. 适用场景与使用边界Langfuse 适合谁LLM 应用开发者需要调试复杂的 Agent、Chain 或工作流理解每一步的输入输出和错误。项目负责人或产品经理需要监控 AI 功能的使用情况、成功率和用户反馈。运维与成本管控人员需要精确统计不同模型、不同用户的 Token 消耗和 API 成本。算法或提示词工程师需要管理不同版本的提示词Prompt并进行 A/B 测试与评估。它能解决什么问题黑盒调试将一次用户问答Session背后的多轮 LLM 调用、工具调用Function Call、检索Retrieval步骤完整记录并可视化。性能监控实时查看请求延迟、失败率、Token 消耗等关键指标。成本分析自动根据官方定价计算每次调用的成本并可按项目、模型、用户等维度聚合。提示词管理将提示词版本化、参数化并与生产流量关联方便迭代优化。数据收集与评估收集生产数据用于后续的监督微调SFT或奖励模型RM训练并支持人工或 LLM-as-a-judge 进行自动评估。使用边界与注意事项非替代日志Langfuse 专注于结构化、语义化的追踪数据对于系统级别的调试如网络、磁盘IO仍需结合传统日志系统如 ELK。数据隐私本地部署确保了数据完全私有。若使用云托管版需仔细阅读其数据协议敏感数据应做脱敏处理。性能开销集成 SDK 会对应用产生轻微的性能开销网络请求、序列化在生产环境应评估其影响通常可异步上报。模型支持其成本计算和部分深度集成依赖于官方模型列表。对于私有化部署或小众模型可能需要自定义配置。3. 环境准备与前置条件本地部署 Langfuse 主要依赖 Docker 环境。以下是详细的准备工作清单。3.1 操作系统支持 Linux (推荐 Ubuntu 20.04)、macOS 和 Windows (WSL2 或 Docker Desktop)。本文演示环境为 Ubuntu 22.04 LTS。3.2 基础软件Docker版本 20.10.0 或更高。确保 Docker 服务已启动。# 检查Docker版本 docker --version # 检查Docker Compose版本通常随Docker Desktop安装 docker-compose --versionGit用于克隆官方仓库。curl或wget用于下载配置文件和测试 API。3.3 资源要求CPU2 核以上。内存至少 4 GB建议 8 GB 以上以确保流畅运行。磁盘空间至少 10 GB 可用空间用于存储数据库和日志。网络需要能访问 Docker Hub 以下拉镜像。首次启动会下载约 1-2 GB 的镜像。3.4 端口检查Langfuse 默认使用以下端口请确保它们未被占用3000: Langfuse Web UI 前端。9020: Langfuse Backend Server API。 如果端口冲突后续可以通过修改docker-compose.yml文件来调整。4. 安装部署与启动方式我们将使用官方推荐的 Docker Compose 方式进行一键部署这是最快捷、依赖最少的方式。4.1 获取部署文件首先从 Langfuse 官方 GitHub 仓库获取最新的docker-compose.yml配置文件。# 创建一个专用目录并进入 mkdir langfuse-local cd langfuse-local # 下载官方提供的docker-compose.yml文件 # 注意请始终从官方仓库获取最新版本 curl -o docker-compose.yml https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml下载完成后你可以用cat docker-compose.yml查看其内容。它定义了 Postgres、Langfuse Server、Langfuse Web 等多个服务。4.2 配置环境变量可选但重要Langfuse 通过环境变量配置密钥、数据库连接等。我们创建一个.env文件来管理。# 复制示例环境变量文件如果官方提供 # 或者直接创建自己的.env文件 cat .env EOF # 用于加密的密钥务必修改为强随机字符串 NEXTAUTH_SECRET$(openssl rand -base64 32) # 用于API认证的密钥务必修改 LANGFUSE_SECRET_KEY$(openssl rand -base64 32) # 数据库连接通常使用docker-compose中定义的Postgres服务 DATABASE_URLpostgresql://postgres:postgrespostgres:5432/postgres DIRECT_URLpostgresql://postgres:postgrespostgres:5432/postgres # 公开访问的URL本地开发设为localhost NEXTAUTH_URLhttp://localhost:3000 LANGFUSE_PUBLIC_HOSThttp://localhost:3000 LANGFUSE_SERVER_HOSThttp://langfuse:9020 # 启用实验性功能如ClickHouse集成按需开启 # LANGFUSE_EXPERIMENTAL_CLICKHOUSE_ENABLEDtrue EOF关键点NEXTAUTH_SECRET和LANGFUSE_SECRET_KEY必须设置为强随机值生产环境尤为重要。4.3 一键启动所有服务配置好环境变量后使用 Docker Compose 启动所有服务。# 在后台启动所有服务 docker-compose up -d # 查看服务启动状态和日志 docker-compose logs -f当你在日志中看到类似以下信息时表示服务已成功启动langfuse-server | Server listening on port 9020 langfuse-web | Ready in xxx ms启动过程可能需要几分钟首次运行需要下载镜像。4.4 验证服务运行服务启动后通过以下方式验证检查容器状态docker-compose ps所有服务的状态应为Up (healthy)或Up。访问 Web UI 打开浏览器访问http://localhost:3000。你应该能看到 Langfuse 的登录/注册页面。测试 Health Checkcurl http://localhost:9020/health应返回{status:OK}。至此Langfuse 平台本身已部署完成。接下来我们需要创建一个项目并获取 API 密钥以便从你的应用发送数据。5. 初始化配置与第一个项目5.1 注册初始管理员账户首次访问http://localhost:3000你会看到注册页面。使用你的邮箱和密码进行注册。第一个注册的用户将成为该实例的超级管理员。登录后你将进入 Dashboard。5.2 创建项目与API密钥在 Dashboard 中点击左侧导航栏的 “Settings” - “Projects”。点击 “Create new project”输入项目名称例如 “My First LLM App”。项目创建后进入该项目设置页面。在 “API Keys” 选项卡下点击 “Create new API key”。Name: 给你的密钥起个名字如 “backend-server”。Role: 选择PROJECT_MEMBER拥有该项目所有权限或根据需要选择更细粒度的角色。点击创建后务必立即复制并妥善保存弹出的Public Key和Secret Key。Secret Key 只显示一次。现在你拥有了访问 Langfuse 的端点http://localhost:3000或你的服务器地址以及一对 API 密钥。接下来我们将把这些密钥集成到一个示例应用中。6. 项目接入与SDK集成我们将创建一个简单的 Python 脚本来模拟一个 LLM 应用并使用 Langfuse Python SDK 上报追踪数据。6.1 环境准备Python项目在你的 LLM 应用项目或一个新的测试目录中操作。# 创建虚拟环境可选但推荐 python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 安装 Langfuse Python SDK 和 OpenAI SDK用于示例 pip install langfuse openai6.2 配置 SDK 并发送第一个 Trace创建一个名为test_langfuse.py的文件。import os from langfuse import Langfuse from langfuse.callback import CallbackHandler import openai from openai import OpenAI # 1. 初始化 Langfuse SDK # 将以下变量替换为你自己的值 LANGFUSE_PUBLIC_KEY pk-lf-xxxxxx # 你的 Public Key LANGFUSE_SECRET_KEY sk-lf-xxxxxx # 你的 Secret Key LANGFUSE_HOST http://localhost:3000 # Langfuse 服务器地址 langfuse Langfuse( public_keyLANGFUSE_PUBLIC_KEY, secret_keyLANGFUSE_SECRET_KEY, hostLANGFUSE_HOST ) # 2. 模拟一个简单的 LLM 调用链Trace # 一个 Trace 代表一次完整的会话或任务 trace langfuse.trace( namecustomer-support-chat, user_iduser-123, metadata{environment: testing, channel: web} ) # 3. 记录一个 Generation代表一次LLM调用 generation trace.generation( namegenerate-response, modelgpt-3.5-turbo, model_parameters{temperature: 0.7, max_tokens: 150}, input用户说我的订单还没发货已经三天了。, metadata{priority: high} ) # 模拟 LLM 的回复实际中这里调用 OpenAI API llm_output 您好非常抱歉给您带来不便。我已经为您查询了订单状态目前显示正在打包中预计明天发出。我们会加急处理发货后您会收到短信通知。 generation.end(outputllm_output) # 4. 记录一个 Span代表链中的一个步骤如检索 span trace.span( nameretrieve-order-details, input{order_id: ORD-789456}, metadata{source: database} ) # ... 执行一些检索逻辑 ... span.end(output{status: packaging, estimated_ship_date: 2023-10-27}) # 5. 记录一个 Event代表一个特定事件 trace.event( nameuser-feedback-received, input{feedback: 客服回复很快, rating: 5} ) print(Trace 数据已发送到 Langfuse。) print(f你可以在 Langfuse UI 中查看此 Trace: {LANGFUSE_HOST}/trace/trace_id)运行这个脚本python test_langfuse.py6.3 在 Langfuse UI 中查看结果回到 Langfuse Dashboard (http://localhost:3000)。在左侧导航栏点击 “Traces”。你应该能看到一条名为 “customer-support-chat” 的新 Trace。点击它将进入详情页。在这里你可以清晰地看到这次会话的完整流程时间线视图以瀑布流形式展示 Trace 下的所有 Generation、Span、Event 及其耗时。详细信息点击每个节点可以查看其输入Input、输出Output、元数据Metadata以及关联的 Token 使用和成本如果配置了模型价格。属性面板查看 Trace 级别的用户 ID、标签、元数据等。通过这个简单的集成你已经实现了最基本的 LLM 调用追踪。但在真实项目中我们通常希望以更无侵入的方式集成例如使用 Langfuse 提供的 Callback Handler 与流行的 LLM 框架如 LangChain、LlamaIndex结合。7. 与 LangChain 深度集成LangChain 是构建 LLM 应用的主流框架之一。Langfuse 为其提供了开箱即用的 Callback Handler可以自动追踪整个 Chain 的执行过程。7.1 安装与配置确保已安装langchain和langchain-openai。pip install langchain langchain-openai7.2 使用 CallbackHandler 自动追踪以下示例展示如何用 Langfuse CallbackHandler 追踪一个简单的 LangChain Chain。import os from langfuse.callback import CallbackHandler from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # 初始化 Langfuse Callback Handler langfuse_handler CallbackHandler( public_keyLANGFUSE_PUBLIC_KEY, secret_keyLANGFUSE_SECRET_KEY, hostLANGFUSE_HOST ) # 设置你的 OpenAI API Key (用于 LangChain 实际调用) os.environ[OPENAI_API_KEY] your-openai-api-key # 1. 创建一个简单的 LangChain Chain prompt ChatPromptTemplate.from_messages([ (system, 你是一个专业的翻译助手。), (user, 请将以下英文翻译成中文{text}) ]) model ChatOpenAI(modelgpt-3.5-turbo) output_parser StrOutputParser() chain prompt | model | output_parser # 2. 使用 Langfuse Handler 调用 Chain # 所有内部的 LLM 调用、工具调用都会被自动捕获并关联到一个 Trace 下。 try: response chain.invoke( {text: Hello, world! This is a test of Langfuse integration with LangChain.}, config{callbacks: [langfuse_handler]} # 关键传入 callback handler ) print(f翻译结果{response}) except Exception as e: print(f调用失败{e}) finally: # 确保所有数据发送完毕 langfuse_handler.flush()运行此脚本后再次查看 Langfuse UI 的 “Traces” 页面。你会看到一个新的 Trace点开后会发现 LangChain 自动创建了更丰富的层级结构清晰展示了 PromptTemplate、LLM 调用等步骤的输入输出和耗时。这种方式极大降低了集成成本。8. 核心功能测试与效果验证现在我们已经完成了部署和基础集成。让我们系统地测试 Langfuse 的几个核心功能验证其效果。8.1 功能一复杂链式调用追踪测试目的验证 Langfuse 能否清晰记录包含多步 LLM 调用、条件判断和工具执行的复杂 Agent 工作流。操作步骤构建一个模拟的 Agent包含planning-web_search(模拟) -summarize三个步骤。使用 SDK 手动创建 Trace并在其中嵌套多个 Span 和 Generation。为关键步骤添加自定义标签和元数据。预期结果在 Langfuse UI 的 Trace 详情页能看到一个层次分明的树状结构每个步骤的起止时间、输入输出、元数据都一目了然。成功标准UI 时间线能正确反映步骤的执行顺序和耗时且数据完整。8.2 功能二Token 与成本计算测试目的验证 Langfuse 能否自动统计 Token 使用量并计算成本。前置条件需要在 Langfuse 项目设置中正确配置所用模型的定价例如 gpt-3.5-turbo 的每百万 Token 价格。对于开源模型或私有模型可能需要手动定义。操作步骤在项目设置的 “Models” 页面添加或确认 OpenAI GPT-3.5 的定价。运行一个或多个包含 LLM 调用的 Trace。预期结果在 Trace 详情页的 Generation 节点上能看到UsagePrompt/Completion Tokens和Cost。在 Dashboard 的 “Metrics” 页面能看到按模型、时间聚合的成本图表。成功标准成本数据非零且计算逻辑符合预期。8.3 功能三提示词Prompt管理与版本化测试目的验证能否将提示词作为独立资产管理并与生产流量关联。操作步骤在 Langfuse UI 中进入 “Prompts” 页面。点击 “Create new prompt”输入名称如 “customer-support-sysprompt”、内容带变量的模板并发布一个版本。在代码中通过 SDK 获取特定版本的提示词内容并用于 LLM 调用。from langfuse import Langfuse langfuse Langfuse(...) prompt langfuse.get_prompt(customer-support-sysprompt) compiled_prompt prompt.compile(customer_toneformal) # 编译变量使用此compiled_prompt发起调用该调用会自动关联到该 Prompt 版本。预期结果在 “Prompts” 页面可以看到每个版本的使用次数、平均延迟、成本等指标。点击一个 Prompt可以看到所有使用了它的 Traces。成功标准能成功获取并编译 Prompt且 UI 中能正确关联 Trace 数据。8.4 功能四数据导出与标注测试目的验证能否从生产 Trace 中导出数据并用于后续的评估或微调。操作步骤在 “Traces” 页面使用过滤器筛选出特定类型的 Trace如包含某个标签的。点击 “Export”可以将这些 Trace 的输入/输出对导出为 CSV 或 JSONL 格式。导出的数据可以用于构建评估数据集Dataset。在 “Datasets” 页面创建数据集并可以人工或通过 LLM-as-a-judge 对结果进行评分。预期结果能顺利导出结构化数据并能在平台上进行基本的标注和评估工作流。成功标准导出文件格式正确包含所需字段。9. 接口 API 与批量任务处理除了 SDKLangfuse 也提供了直接的 REST API方便其他语言或批量任务集成。9.1 核心 API 端点速览POST /api/public/traces: 创建或更新一个 Trace。POST /api/public/observations: 创建 Trace 下的一个观察项Generation/Span/Event。GET /api/public/datasets: 获取数据集列表。更多 API 请参考官方文档https://langfuse.com/docs/api本地部署请替换为你的地址。9.2 使用 cURL 测试 API你可以使用 cURL 或任何 HTTP 客户端直接与 Langfuse Server 交互。# 创建一个 Trace curl -X POST http://localhost:9020/api/public/traces \ -H Content-Type: application/json \ -H Authorization: Bearer ${LANGFUSE_SECRET_KEY} \ -d { id: trace_curl_1, name: API-Created-Trace, userId: user-curl, metadata: {source: curl-test} } # 为该 Trace 添加一个 Generation curl -X POST http://localhost:9020/api/public/observations \ -H Content-Type: application/json \ -H Authorization: Bearer ${LANGFUSE_SECRET_KEY} \ -d { traceId: trace_curl_1, type: GENERATION, name: llm-call-via-api, input: What is Langfuse?, output: Langfuse is an open-source observability platform for LLM applications., model: gpt-3.5-turbo, modelParameters: {temperature: 0} }9.3 批量任务处理建议对于离线批量处理或异步任务建议采用以下模式为每个批量作业创建独立的 Trace使用一个共同的sessionId或batchId在元数据中标识。异步上报使用 SDK 的异步模式或消息队列避免阻塞主任务流程。Python SDK 默认是异步的。错误处理与重试网络可能不稳定上报失败时应记录日志并设计重试机制避免数据丢失。控制数据粒度对于海量、低价值的中间步骤可以考虑抽样上报或聚合后上报以平衡数据价值和存储成本。10. 资源占用与性能观察本地部署后需要关注其资源消耗尤其是在处理高并发追踪数据时。10.1 监控服务状态使用 Docker 命令查看资源使用情况# 查看所有容器的资源占用CPU内存 docker stats # 查看特定服务的日志 docker-compose logs -f langfuse-server10.2 性能影响因素数据量每个 Trace、Observation 都会写入数据库。高频、高细粒度的追踪会产生大量数据。PostgreSQL 性能默认的 Docker Compose 配置使用基础 PostgreSQL。对于生产环境应考虑为 PostgreSQL 容器分配更多内存。使用更强大的主机或云数据库服务。定期清理旧数据Langfuse 支持设置数据保留策略。网络延迟SDK 默认是异步上报但对延迟敏感的应用仍需评估网络往返时间的影响。10.3 优化建议采样Sampling在生产环境中不必记录 100% 的请求。可以在 SDK 初始化时设置采样率。langfuse Langfuse( public_key..., secret_key..., host..., sample_rate0.1 # 只记录10%的请求 )批量上报SDK 会自动将事件批量发送以减少请求数。使用 ClickHouse实验性对于超大规模的数据分析场景可以启用 ClickHouse 集成来提升查询性能。这需要在.env和docker-compose.yml中进行额外配置。11. 常见问题与排查方法在部署和使用过程中你可能会遇到以下问题。问题现象可能原因排查方式解决方案访问localhost:3000失败1. 服务未启动成功2. 端口被占用3. 防火墙限制1.docker-compose ps检查状态2.docker-compose logs查看错误日志3.netstat -tulnp | grep :3000检查端口1. 根据日志修复错误常见数据库连接失败2. 修改docker-compose.yml中的端口映射3. 确保防火墙开放相应端口SDK 上报数据后 UI 不显示1. API 密钥错误2. 网络不通3. 数据异步处理延迟1. 检查LANGFUSE_PUBLIC_KEY和LANGFUSE_SECRET_KEY是否正确2. 用curl测试 API 端点连通性3. 等待几秒刷新页面1. 重新生成并配置正确的 API 密钥2. 确保应用能访问LANGFUSE_HOST3. 调用langfuse.flush()强制同步Docker 容器启动失败提示数据库错误1. 数据库卷权限问题2..env文件配置错误3. 旧数据不兼容1. 查看langfuse-server容器的日志2. 检查.env中DATABASE_URL格式1. 尝试docker-compose down -v清除卷再重启警告会丢失所有数据2. 核对.env文件与docker-compose.yml中的服务名、密码是否一致Trace 详情页加载缓慢1. 单次 Trace 包含的 Observation 过多2. 数据库性能瓶颈1. 检查该 Trace 下的节点数量2. 查看数据库监控1. 优化代码避免创建过于细碎的 Observation2. 考虑对数据库进行性能调优或升级成本计算为 0 或不准1. 模型定价未配置2. SDK 上报时未指定model字段3. 使用了自定义/私有模型1. 进入项目设置 - Models 页面检查2. 检查 Generation 记录的model字段1. 在设置中补充模型定价2. 确保调用 SDK 时传入了正确的model参数3. 为自定义模型创建定价条目12. 最佳实践与使用建议为了更高效、安全地使用 Langfuse遵循以下实践建议环境隔离为开发、测试、生产环境部署独立的 Langfuse 实例并使用不同的项目和 API 密钥避免数据污染。密钥管理切勿将SECRET_KEY提交到版本控制系统如 Git。始终通过环境变量或密钥管理服务如 Vault传递。数据脱敏在追踪可能包含用户个人信息PII或敏感数据时在 SDK 上报前进行脱敏处理或在 Langfuse 中利用数据清洗规则。结构化 Metadata充分利用metadata和tags字段为 Trace 和 Observation 添加结构化的业务上下文如feature_name,ab_test_group便于后续筛选和分析。定义清晰的命名规范为Trace.name、Span.name、Generation.name制定团队规范例如使用动词-名词格式如retrieve-document,generate-summary这样在查看大量 Traces 时更容易理解。从关键链路开始不必一次性追踪所有代码。先从最核心、最不稳定的 LLM 调用链开始集成快速获得价值再逐步扩大范围。定期审查与清理建立数据保留策略定期归档或清理旧的追踪数据以控制存储成本并保持系统性能。结合告警利用 Langfuse 的指标如高延迟、高失败率设置阈值并集成到团队的告警系统如 Slack、PagerDuty中实现主动监控。通过本文的步骤你应该已经成功在本地部署了 Langfuse并将其接入到了一个示例应用中。这个平台的价值在于它将 LLM 应用从“黑盒”变成了“白盒”让开发、调试、优化和成本管控变得有据可依。接下来你可以尝试将其集成到真实的项目中去从监控一个简单的聊天接口开始逐步扩展到复杂的 Agent 工作流持续积累你的 AI 可观测性数据资产。 Langfuse本地部署与LLM应用可观测性实践指南
如果你正在开发或使用大语言模型LLM应用那么“模型表现不稳定”、“调试黑盒”、“成本不可控”这些问题大概率已经让你头疼不已。Langfuse 就是为解决这些痛点而生的开源可观测性平台它专为 LLM 应用设计能帮你追踪每一次调用、分析每一次成本、调试每一次异常。简单说它就像给 LLM 应用装上了“行车记录仪”和“性能分析仪”。这篇文章不空谈概念直接带你从零开始完成 Langfuse 最新版的本地部署、配置并接入一个示例项目。你会看到如何一键启动服务、如何通过几行代码集成 SDK、以及如何利用其强大的 Dashboard 进行追踪和调试。无论你是想监控自己开发的 AI 应用还是想优化基于 OpenAI、Anthropic 等服务的调用这套方案都能让你快速获得可见性。1. 核心能力速览在动手之前先快速了解 Langfuse 能做什么以及你需要准备什么。能力项说明项目类型开源 LLM 应用可观测性Observability平台核心功能追踪Tracing、日志Logging、评估Evaluation、数据标注Dataset Prompt Management部署方式支持 Docker Compose 一键部署推荐也支持云托管Langfuse Cloud数据存储使用 PostgreSQL 作为主数据库可选集成 ClickHouse 用于分析硬件门槛本地部署对显存无要求。主要消耗内存和 CPU 资源建议 4GB 内存。启动方式通过docker-compose up -d命令一键启动所有服务Web、Server、Worker。接口能力提供 RESTful API 和多种语言的 SDKPython、JS/TS、Java等便于项目集成。监控维度追踪链式调用、记录输入输出、计算 Token 使用与成本、分析延迟、进行人工或自动评估。适合场景开发调试 LLM 应用、生产环境监控与告警、分析用量与成本优化、管理提示词版本。简单来说你可以把它看作一个自托管的“增强版日志系统”专门为 AI 应用的复杂链式调用Chain/Trace设计提供了开箱即用的可视化界面。2. 适用场景与使用边界Langfuse 适合谁LLM 应用开发者需要调试复杂的 Agent、Chain 或工作流理解每一步的输入输出和错误。项目负责人或产品经理需要监控 AI 功能的使用情况、成功率和用户反馈。运维与成本管控人员需要精确统计不同模型、不同用户的 Token 消耗和 API 成本。算法或提示词工程师需要管理不同版本的提示词Prompt并进行 A/B 测试与评估。它能解决什么问题黑盒调试将一次用户问答Session背后的多轮 LLM 调用、工具调用Function Call、检索Retrieval步骤完整记录并可视化。性能监控实时查看请求延迟、失败率、Token 消耗等关键指标。成本分析自动根据官方定价计算每次调用的成本并可按项目、模型、用户等维度聚合。提示词管理将提示词版本化、参数化并与生产流量关联方便迭代优化。数据收集与评估收集生产数据用于后续的监督微调SFT或奖励模型RM训练并支持人工或 LLM-as-a-judge 进行自动评估。使用边界与注意事项非替代日志Langfuse 专注于结构化、语义化的追踪数据对于系统级别的调试如网络、磁盘IO仍需结合传统日志系统如 ELK。数据隐私本地部署确保了数据完全私有。若使用云托管版需仔细阅读其数据协议敏感数据应做脱敏处理。性能开销集成 SDK 会对应用产生轻微的性能开销网络请求、序列化在生产环境应评估其影响通常可异步上报。模型支持其成本计算和部分深度集成依赖于官方模型列表。对于私有化部署或小众模型可能需要自定义配置。3. 环境准备与前置条件本地部署 Langfuse 主要依赖 Docker 环境。以下是详细的准备工作清单。3.1 操作系统支持 Linux (推荐 Ubuntu 20.04)、macOS 和 Windows (WSL2 或 Docker Desktop)。本文演示环境为 Ubuntu 22.04 LTS。3.2 基础软件Docker版本 20.10.0 或更高。确保 Docker 服务已启动。# 检查Docker版本 docker --version # 检查Docker Compose版本通常随Docker Desktop安装 docker-compose --versionGit用于克隆官方仓库。curl或wget用于下载配置文件和测试 API。3.3 资源要求CPU2 核以上。内存至少 4 GB建议 8 GB 以上以确保流畅运行。磁盘空间至少 10 GB 可用空间用于存储数据库和日志。网络需要能访问 Docker Hub 以下拉镜像。首次启动会下载约 1-2 GB 的镜像。3.4 端口检查Langfuse 默认使用以下端口请确保它们未被占用3000: Langfuse Web UI 前端。9020: Langfuse Backend Server API。 如果端口冲突后续可以通过修改docker-compose.yml文件来调整。4. 安装部署与启动方式我们将使用官方推荐的 Docker Compose 方式进行一键部署这是最快捷、依赖最少的方式。4.1 获取部署文件首先从 Langfuse 官方 GitHub 仓库获取最新的docker-compose.yml配置文件。# 创建一个专用目录并进入 mkdir langfuse-local cd langfuse-local # 下载官方提供的docker-compose.yml文件 # 注意请始终从官方仓库获取最新版本 curl -o docker-compose.yml https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml下载完成后你可以用cat docker-compose.yml查看其内容。它定义了 Postgres、Langfuse Server、Langfuse Web 等多个服务。4.2 配置环境变量可选但重要Langfuse 通过环境变量配置密钥、数据库连接等。我们创建一个.env文件来管理。# 复制示例环境变量文件如果官方提供 # 或者直接创建自己的.env文件 cat .env EOF # 用于加密的密钥务必修改为强随机字符串 NEXTAUTH_SECRET$(openssl rand -base64 32) # 用于API认证的密钥务必修改 LANGFUSE_SECRET_KEY$(openssl rand -base64 32) # 数据库连接通常使用docker-compose中定义的Postgres服务 DATABASE_URLpostgresql://postgres:postgrespostgres:5432/postgres DIRECT_URLpostgresql://postgres:postgrespostgres:5432/postgres # 公开访问的URL本地开发设为localhost NEXTAUTH_URLhttp://localhost:3000 LANGFUSE_PUBLIC_HOSThttp://localhost:3000 LANGFUSE_SERVER_HOSThttp://langfuse:9020 # 启用实验性功能如ClickHouse集成按需开启 # LANGFUSE_EXPERIMENTAL_CLICKHOUSE_ENABLEDtrue EOF关键点NEXTAUTH_SECRET和LANGFUSE_SECRET_KEY必须设置为强随机值生产环境尤为重要。4.3 一键启动所有服务配置好环境变量后使用 Docker Compose 启动所有服务。# 在后台启动所有服务 docker-compose up -d # 查看服务启动状态和日志 docker-compose logs -f当你在日志中看到类似以下信息时表示服务已成功启动langfuse-server | Server listening on port 9020 langfuse-web | Ready in xxx ms启动过程可能需要几分钟首次运行需要下载镜像。4.4 验证服务运行服务启动后通过以下方式验证检查容器状态docker-compose ps所有服务的状态应为Up (healthy)或Up。访问 Web UI 打开浏览器访问http://localhost:3000。你应该能看到 Langfuse 的登录/注册页面。测试 Health Checkcurl http://localhost:9020/health应返回{status:OK}。至此Langfuse 平台本身已部署完成。接下来我们需要创建一个项目并获取 API 密钥以便从你的应用发送数据。5. 初始化配置与第一个项目5.1 注册初始管理员账户首次访问http://localhost:3000你会看到注册页面。使用你的邮箱和密码进行注册。第一个注册的用户将成为该实例的超级管理员。登录后你将进入 Dashboard。5.2 创建项目与API密钥在 Dashboard 中点击左侧导航栏的 “Settings” - “Projects”。点击 “Create new project”输入项目名称例如 “My First LLM App”。项目创建后进入该项目设置页面。在 “API Keys” 选项卡下点击 “Create new API key”。Name: 给你的密钥起个名字如 “backend-server”。Role: 选择PROJECT_MEMBER拥有该项目所有权限或根据需要选择更细粒度的角色。点击创建后务必立即复制并妥善保存弹出的Public Key和Secret Key。Secret Key 只显示一次。现在你拥有了访问 Langfuse 的端点http://localhost:3000或你的服务器地址以及一对 API 密钥。接下来我们将把这些密钥集成到一个示例应用中。6. 项目接入与SDK集成我们将创建一个简单的 Python 脚本来模拟一个 LLM 应用并使用 Langfuse Python SDK 上报追踪数据。6.1 环境准备Python项目在你的 LLM 应用项目或一个新的测试目录中操作。# 创建虚拟环境可选但推荐 python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 安装 Langfuse Python SDK 和 OpenAI SDK用于示例 pip install langfuse openai6.2 配置 SDK 并发送第一个 Trace创建一个名为test_langfuse.py的文件。import os from langfuse import Langfuse from langfuse.callback import CallbackHandler import openai from openai import OpenAI # 1. 初始化 Langfuse SDK # 将以下变量替换为你自己的值 LANGFUSE_PUBLIC_KEY pk-lf-xxxxxx # 你的 Public Key LANGFUSE_SECRET_KEY sk-lf-xxxxxx # 你的 Secret Key LANGFUSE_HOST http://localhost:3000 # Langfuse 服务器地址 langfuse Langfuse( public_keyLANGFUSE_PUBLIC_KEY, secret_keyLANGFUSE_SECRET_KEY, hostLANGFUSE_HOST ) # 2. 模拟一个简单的 LLM 调用链Trace # 一个 Trace 代表一次完整的会话或任务 trace langfuse.trace( namecustomer-support-chat, user_iduser-123, metadata{environment: testing, channel: web} ) # 3. 记录一个 Generation代表一次LLM调用 generation trace.generation( namegenerate-response, modelgpt-3.5-turbo, model_parameters{temperature: 0.7, max_tokens: 150}, input用户说我的订单还没发货已经三天了。, metadata{priority: high} ) # 模拟 LLM 的回复实际中这里调用 OpenAI API llm_output 您好非常抱歉给您带来不便。我已经为您查询了订单状态目前显示正在打包中预计明天发出。我们会加急处理发货后您会收到短信通知。 generation.end(outputllm_output) # 4. 记录一个 Span代表链中的一个步骤如检索 span trace.span( nameretrieve-order-details, input{order_id: ORD-789456}, metadata{source: database} ) # ... 执行一些检索逻辑 ... span.end(output{status: packaging, estimated_ship_date: 2023-10-27}) # 5. 记录一个 Event代表一个特定事件 trace.event( nameuser-feedback-received, input{feedback: 客服回复很快, rating: 5} ) print(Trace 数据已发送到 Langfuse。) print(f你可以在 Langfuse UI 中查看此 Trace: {LANGFUSE_HOST}/trace/trace_id)运行这个脚本python test_langfuse.py6.3 在 Langfuse UI 中查看结果回到 Langfuse Dashboard (http://localhost:3000)。在左侧导航栏点击 “Traces”。你应该能看到一条名为 “customer-support-chat” 的新 Trace。点击它将进入详情页。在这里你可以清晰地看到这次会话的完整流程时间线视图以瀑布流形式展示 Trace 下的所有 Generation、Span、Event 及其耗时。详细信息点击每个节点可以查看其输入Input、输出Output、元数据Metadata以及关联的 Token 使用和成本如果配置了模型价格。属性面板查看 Trace 级别的用户 ID、标签、元数据等。通过这个简单的集成你已经实现了最基本的 LLM 调用追踪。但在真实项目中我们通常希望以更无侵入的方式集成例如使用 Langfuse 提供的 Callback Handler 与流行的 LLM 框架如 LangChain、LlamaIndex结合。7. 与 LangChain 深度集成LangChain 是构建 LLM 应用的主流框架之一。Langfuse 为其提供了开箱即用的 Callback Handler可以自动追踪整个 Chain 的执行过程。7.1 安装与配置确保已安装langchain和langchain-openai。pip install langchain langchain-openai7.2 使用 CallbackHandler 自动追踪以下示例展示如何用 Langfuse CallbackHandler 追踪一个简单的 LangChain Chain。import os from langfuse.callback import CallbackHandler from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # 初始化 Langfuse Callback Handler langfuse_handler CallbackHandler( public_keyLANGFUSE_PUBLIC_KEY, secret_keyLANGFUSE_SECRET_KEY, hostLANGFUSE_HOST ) # 设置你的 OpenAI API Key (用于 LangChain 实际调用) os.environ[OPENAI_API_KEY] your-openai-api-key # 1. 创建一个简单的 LangChain Chain prompt ChatPromptTemplate.from_messages([ (system, 你是一个专业的翻译助手。), (user, 请将以下英文翻译成中文{text}) ]) model ChatOpenAI(modelgpt-3.5-turbo) output_parser StrOutputParser() chain prompt | model | output_parser # 2. 使用 Langfuse Handler 调用 Chain # 所有内部的 LLM 调用、工具调用都会被自动捕获并关联到一个 Trace 下。 try: response chain.invoke( {text: Hello, world! This is a test of Langfuse integration with LangChain.}, config{callbacks: [langfuse_handler]} # 关键传入 callback handler ) print(f翻译结果{response}) except Exception as e: print(f调用失败{e}) finally: # 确保所有数据发送完毕 langfuse_handler.flush()运行此脚本后再次查看 Langfuse UI 的 “Traces” 页面。你会看到一个新的 Trace点开后会发现 LangChain 自动创建了更丰富的层级结构清晰展示了 PromptTemplate、LLM 调用等步骤的输入输出和耗时。这种方式极大降低了集成成本。8. 核心功能测试与效果验证现在我们已经完成了部署和基础集成。让我们系统地测试 Langfuse 的几个核心功能验证其效果。8.1 功能一复杂链式调用追踪测试目的验证 Langfuse 能否清晰记录包含多步 LLM 调用、条件判断和工具执行的复杂 Agent 工作流。操作步骤构建一个模拟的 Agent包含planning-web_search(模拟) -summarize三个步骤。使用 SDK 手动创建 Trace并在其中嵌套多个 Span 和 Generation。为关键步骤添加自定义标签和元数据。预期结果在 Langfuse UI 的 Trace 详情页能看到一个层次分明的树状结构每个步骤的起止时间、输入输出、元数据都一目了然。成功标准UI 时间线能正确反映步骤的执行顺序和耗时且数据完整。8.2 功能二Token 与成本计算测试目的验证 Langfuse 能否自动统计 Token 使用量并计算成本。前置条件需要在 Langfuse 项目设置中正确配置所用模型的定价例如 gpt-3.5-turbo 的每百万 Token 价格。对于开源模型或私有模型可能需要手动定义。操作步骤在项目设置的 “Models” 页面添加或确认 OpenAI GPT-3.5 的定价。运行一个或多个包含 LLM 调用的 Trace。预期结果在 Trace 详情页的 Generation 节点上能看到UsagePrompt/Completion Tokens和Cost。在 Dashboard 的 “Metrics” 页面能看到按模型、时间聚合的成本图表。成功标准成本数据非零且计算逻辑符合预期。8.3 功能三提示词Prompt管理与版本化测试目的验证能否将提示词作为独立资产管理并与生产流量关联。操作步骤在 Langfuse UI 中进入 “Prompts” 页面。点击 “Create new prompt”输入名称如 “customer-support-sysprompt”、内容带变量的模板并发布一个版本。在代码中通过 SDK 获取特定版本的提示词内容并用于 LLM 调用。from langfuse import Langfuse langfuse Langfuse(...) prompt langfuse.get_prompt(customer-support-sysprompt) compiled_prompt prompt.compile(customer_toneformal) # 编译变量使用此compiled_prompt发起调用该调用会自动关联到该 Prompt 版本。预期结果在 “Prompts” 页面可以看到每个版本的使用次数、平均延迟、成本等指标。点击一个 Prompt可以看到所有使用了它的 Traces。成功标准能成功获取并编译 Prompt且 UI 中能正确关联 Trace 数据。8.4 功能四数据导出与标注测试目的验证能否从生产 Trace 中导出数据并用于后续的评估或微调。操作步骤在 “Traces” 页面使用过滤器筛选出特定类型的 Trace如包含某个标签的。点击 “Export”可以将这些 Trace 的输入/输出对导出为 CSV 或 JSONL 格式。导出的数据可以用于构建评估数据集Dataset。在 “Datasets” 页面创建数据集并可以人工或通过 LLM-as-a-judge 对结果进行评分。预期结果能顺利导出结构化数据并能在平台上进行基本的标注和评估工作流。成功标准导出文件格式正确包含所需字段。9. 接口 API 与批量任务处理除了 SDKLangfuse 也提供了直接的 REST API方便其他语言或批量任务集成。9.1 核心 API 端点速览POST /api/public/traces: 创建或更新一个 Trace。POST /api/public/observations: 创建 Trace 下的一个观察项Generation/Span/Event。GET /api/public/datasets: 获取数据集列表。更多 API 请参考官方文档https://langfuse.com/docs/api本地部署请替换为你的地址。9.2 使用 cURL 测试 API你可以使用 cURL 或任何 HTTP 客户端直接与 Langfuse Server 交互。# 创建一个 Trace curl -X POST http://localhost:9020/api/public/traces \ -H Content-Type: application/json \ -H Authorization: Bearer ${LANGFUSE_SECRET_KEY} \ -d { id: trace_curl_1, name: API-Created-Trace, userId: user-curl, metadata: {source: curl-test} } # 为该 Trace 添加一个 Generation curl -X POST http://localhost:9020/api/public/observations \ -H Content-Type: application/json \ -H Authorization: Bearer ${LANGFUSE_SECRET_KEY} \ -d { traceId: trace_curl_1, type: GENERATION, name: llm-call-via-api, input: What is Langfuse?, output: Langfuse is an open-source observability platform for LLM applications., model: gpt-3.5-turbo, modelParameters: {temperature: 0} }9.3 批量任务处理建议对于离线批量处理或异步任务建议采用以下模式为每个批量作业创建独立的 Trace使用一个共同的sessionId或batchId在元数据中标识。异步上报使用 SDK 的异步模式或消息队列避免阻塞主任务流程。Python SDK 默认是异步的。错误处理与重试网络可能不稳定上报失败时应记录日志并设计重试机制避免数据丢失。控制数据粒度对于海量、低价值的中间步骤可以考虑抽样上报或聚合后上报以平衡数据价值和存储成本。10. 资源占用与性能观察本地部署后需要关注其资源消耗尤其是在处理高并发追踪数据时。10.1 监控服务状态使用 Docker 命令查看资源使用情况# 查看所有容器的资源占用CPU内存 docker stats # 查看特定服务的日志 docker-compose logs -f langfuse-server10.2 性能影响因素数据量每个 Trace、Observation 都会写入数据库。高频、高细粒度的追踪会产生大量数据。PostgreSQL 性能默认的 Docker Compose 配置使用基础 PostgreSQL。对于生产环境应考虑为 PostgreSQL 容器分配更多内存。使用更强大的主机或云数据库服务。定期清理旧数据Langfuse 支持设置数据保留策略。网络延迟SDK 默认是异步上报但对延迟敏感的应用仍需评估网络往返时间的影响。10.3 优化建议采样Sampling在生产环境中不必记录 100% 的请求。可以在 SDK 初始化时设置采样率。langfuse Langfuse( public_key..., secret_key..., host..., sample_rate0.1 # 只记录10%的请求 )批量上报SDK 会自动将事件批量发送以减少请求数。使用 ClickHouse实验性对于超大规模的数据分析场景可以启用 ClickHouse 集成来提升查询性能。这需要在.env和docker-compose.yml中进行额外配置。11. 常见问题与排查方法在部署和使用过程中你可能会遇到以下问题。问题现象可能原因排查方式解决方案访问localhost:3000失败1. 服务未启动成功2. 端口被占用3. 防火墙限制1.docker-compose ps检查状态2.docker-compose logs查看错误日志3.netstat -tulnp | grep :3000检查端口1. 根据日志修复错误常见数据库连接失败2. 修改docker-compose.yml中的端口映射3. 确保防火墙开放相应端口SDK 上报数据后 UI 不显示1. API 密钥错误2. 网络不通3. 数据异步处理延迟1. 检查LANGFUSE_PUBLIC_KEY和LANGFUSE_SECRET_KEY是否正确2. 用curl测试 API 端点连通性3. 等待几秒刷新页面1. 重新生成并配置正确的 API 密钥2. 确保应用能访问LANGFUSE_HOST3. 调用langfuse.flush()强制同步Docker 容器启动失败提示数据库错误1. 数据库卷权限问题2..env文件配置错误3. 旧数据不兼容1. 查看langfuse-server容器的日志2. 检查.env中DATABASE_URL格式1. 尝试docker-compose down -v清除卷再重启警告会丢失所有数据2. 核对.env文件与docker-compose.yml中的服务名、密码是否一致Trace 详情页加载缓慢1. 单次 Trace 包含的 Observation 过多2. 数据库性能瓶颈1. 检查该 Trace 下的节点数量2. 查看数据库监控1. 优化代码避免创建过于细碎的 Observation2. 考虑对数据库进行性能调优或升级成本计算为 0 或不准1. 模型定价未配置2. SDK 上报时未指定model字段3. 使用了自定义/私有模型1. 进入项目设置 - Models 页面检查2. 检查 Generation 记录的model字段1. 在设置中补充模型定价2. 确保调用 SDK 时传入了正确的model参数3. 为自定义模型创建定价条目12. 最佳实践与使用建议为了更高效、安全地使用 Langfuse遵循以下实践建议环境隔离为开发、测试、生产环境部署独立的 Langfuse 实例并使用不同的项目和 API 密钥避免数据污染。密钥管理切勿将SECRET_KEY提交到版本控制系统如 Git。始终通过环境变量或密钥管理服务如 Vault传递。数据脱敏在追踪可能包含用户个人信息PII或敏感数据时在 SDK 上报前进行脱敏处理或在 Langfuse 中利用数据清洗规则。结构化 Metadata充分利用metadata和tags字段为 Trace 和 Observation 添加结构化的业务上下文如feature_name,ab_test_group便于后续筛选和分析。定义清晰的命名规范为Trace.name、Span.name、Generation.name制定团队规范例如使用动词-名词格式如retrieve-document,generate-summary这样在查看大量 Traces 时更容易理解。从关键链路开始不必一次性追踪所有代码。先从最核心、最不稳定的 LLM 调用链开始集成快速获得价值再逐步扩大范围。定期审查与清理建立数据保留策略定期归档或清理旧的追踪数据以控制存储成本并保持系统性能。结合告警利用 Langfuse 的指标如高延迟、高失败率设置阈值并集成到团队的告警系统如 Slack、PagerDuty中实现主动监控。通过本文的步骤你应该已经成功在本地部署了 Langfuse并将其接入到了一个示例应用中。这个平台的价值在于它将 LLM 应用从“黑盒”变成了“白盒”让开发、调试、优化和成本管控变得有据可依。接下来你可以尝试将其集成到真实的项目中去从监控一个简单的聊天接口开始逐步扩展到复杂的 Agent 工作流持续积累你的 AI 可观测性数据资产。