Langfuse 部署与配置教程 Agent本文介绍如何为 Agent 项目部署LangfuseLLM 可观测 / Tracing 平台并把项目接入其中实现每次大模型调用的追踪与可视化。官网 Langfuse一、Langfuse 是什么Langfuse 是一个开源的LLM 可观测性平台用来记录、追踪、分析每一次大模型调用Trace追踪把一次完整的 LLM 调用链路prompt → 回复 token → 耗时 → 成本记录成一条 trace。可视化Web 界面按项目维度展示所有调用可按模型 / 时间检索。调试查看每次调用实际发送的 prompt 与返回结果排查生成质量问题。本项目把 Langfuse 以langchain callback handler的方式挂载到 LLM 客户端上无需改造业务生成逻辑。二、整体架构[ Agent 服务] ──(HTTPS/HTTP)──► [Langfuse 服务Web 采集] │ │ └── 读取 LANGFUSE_* 环境变量 └── 存 PostgreSQL可选客户端AgentPythonlangchain通过LANGFUSE_*环境变量连接 Langfuse。服务端Langfuse 提供 Web UI3000端口与采集 API。三、服务端部署 LangfuseDocker以下以Langfuse 官方镜像 Docker Compose为例。 Agent 项目里已有 langsmith 的自托管配置docker-compose.langsmith.ymlLangfuse 需另行部署一套。1. 准备docker-compose.langfuse.yml在服务器上新建一个目录例如~/langfuse创建如下文件services: langfuse: image: ghcr.io/langfuse/langfuse:latest container_name: langfuse restart: unless-stopped ports: - 3000:3000 # 重要NEXTAUTH_URL 与 LANGFUSE_PUBLIC_URL 需让客户端能访问到 environment: DATABASE_URL: postgresql://postgres:LANGFFUSE_DB_PASSWORDlangfuse-db:5432/langfuse # 无外部 OAuth 时使用一个强随机密钥openssl rand -base64 32 NEXTAUTH_SECRET: 你的随机SHA256 SALT: 你的随机hex NEXTAUTH_URL: http://192.168.1.7:3000 LANGFUSE_PUBLIC_URL: http://192.168.1.7:3000 # 首次启动的初始管理员改掉 INIT_PROJECT_ID: 216879ad-14da-4daa-9a96-368b9305d393 INIT_PROJECT_PUBLIC_KEY: pk-lf-YOUR_PUBLIC_KEY INIT_PROJECT_SECRET_KEY: sk-lf-YOUR_SECRET_KEY INIT_PROJECT_NAME: default INIT_USER_EMAIL: adminexample.com INIT_USER_PASSWORD: 改我 INIT_USER_NAME: Admin depends_on: langfuse-db: condition: service_healthy healthcheck: test: [CMD, wget, -qO-, http://127.0.0.1:3000/api/public/health] interval: 30s timeout: 5s retries: 10 langfuse-db: image: postgres:15-alpine container_name: langfuse-db restart: unless-stopped environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: LANGFFUSE_DB_PASSWORD POSTGRES_DB: langfuse volumes: - langfuse-db-data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 5s timeout: 5s retries: 30 volumes: langfuse-db-data:TIP上面的INIT_PROJECT_PUBLIC_KEY/INIT_PROJECT_SECRET_KEY/INIT_PROJECT_ID/SALT/NEXTAUTH_SECRET需要先生成。Langfuse 官方提供一键生成脚本也可在首次启动 Web 界面后手动创建项目并拿 key见第五节。2. 生成密钥# NEXTAUTH_SECRET openssl rand -base64 32 # SALT openssl rand -hex 163. 启动docker compose -f docker-compose.langfuse.yml up -d docker compose -f docker-compose.langfuse.yml logs -f langfuse启动成功后访问http://服务器IP:3000。四、客户端 Agent 接入 Langfuse1. 依赖项目requirements.txt中已包含 Langfuse 与 langchainlangfuse4.0 langchain1.0一次性安装# 本地 venv ./.venv/bin/pip install langfuse langchain # 或 Docker 构建时由 Dockerfile 自动安装2. 环境变量关键在agent/.envconfig.py 优先读取的那个而非根目录 .env中加入LANGFUSE_ENABLEDtrue LANGFUSE_SECRET_KEYsk-lf-xxxxx LANGFUSE_PUBLIC_KEYpk-lf-xxxxx LANGFUSE_BASE_URLhttp://192.168.1.7:3000⚠️改在哪个 .env 很关键本项目src/config.py用load_dotenv(BASE_DIR/.env)优先读取agent/.env。若只改根目录.envdocker 的env_file会被agent/.env里的旧值覆盖。3. 代码接入点已实现Langfuse 通过CallbackHandler挂载在两个 LLM 客户端上agent/src/llm/llm_client.py_build_callback_manager()→get_llm()使用。agent/src/agents/outline_agent.py直接 new 的ChatOpenAI同样挂载。# 核心逻辑llm_client.py def _build_callback_manager(): if not settings.langfuse_enabled or not settings.langfuse_public_key: return None from langfuse import Langfuse from langfuse.langchain import CallbackHandler Langfuse() # 用环境变量初始化客户端必须是单例先于 handler 创建 handler CallbackHandler() return CallbackManager([handler])易错点langfuse 4.x 的CallbackHandler不接受secret_key/host参数而是从环境变量读取。必须先Langfuse()注册客户端实例再CallbackHandler()否则会返回tracing_enabledFalse的空客户端表现为没追踪数据。4. 校验是否生效在agent目录下执行../.venv/bin/python -c from src.llm.llm_client import _build_callback_manager cm _build_callback_manager() c cm.handlers[0]._langfuse_client print(base_url, c._base_url, | tracing_enabled, c._tracing_enabled) 期望输出base_url http://192.168.1.7:3000 | tracing_enabled True。五、在 Langfuse Web 界面获取 Key访问http://服务器IP:3000。用初始管理员账号登录若未在镜像里配置初始项目会引导你创建。创建 / 进入一个Project项目。Project 右上角 / Public Key 处点开可复制Public Keypk-lf-...与Secret Keysk-lf-...。把这两个 key 服务器地址填入agent/.env的LANGFUSE_*。安全提醒SECRET_KEY只能完整查看一次。切勿提交进 git—— Agent 的.gitignore已忽略.env但历史上 .env 曾被提交过见文末「历史遗留问题」请务必确保 key 不落入版本库。六、服务器部署后的更新流程服务器上改了agent/.env后需重启容器才能生效Langfuse 客户端是进程级单例进程内不会重读环境变量docker compose restart app若同时更新了代码含前端需重新构建docker compose up -d --build app⚠️前后端不同步陷阱Docker 镜像里的前端是构建镜像时打包的dist。只更新源码不--build服务器跑的还是旧前端。本地上看的是最新源码dev所以会界面不一样——部署改动必须--build。七、常见问题排查现象原因 / 处理Web 界面看得到 trace但服务器流量不进去服务器的LANGFUSE_BASE_URL是内网 IP客户端连不上改成都可访问的地址或与 langfuse 同机用http://127.0.0.1:3000tracing_enabledFalse没有先Langfuse()再CallbackHandler()或环境变量没读对改错.env改了 .env 但没变化Langfuse 客户端是进程级缓存单例需要重启容器有 trace 但缺数据确认LANGFUSE_ENABLEDtrue且 public/secret key 与 Web 界面项目匹配Docker 前端跟不上源码部署时必须docker compose up -d --build否则还是旧 dist
企业数字化 ERP 产品动态
相关推荐
GridView自动换行显示实战：用TaoToken统一Key打通AI辅助布局调试 /* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/9/26 16:12:27
AI Agent 可观测性实战：用 TaoToken 统一 Key 打通智能体监控链路 /* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/9/26 16:12:27
城乡规划论文的底图数据与图层对齐：现场调研数据对不上时的全流程排查指南 底图数据与现场调研数据对不上，在城乡规划论文里通常不是单一错误，而是采集口径、落点规则、图层对齐三个环节中有一处没定清楚。想快速找到问题，先查两套数据各自「从哪里来、按什么规则画」，再回到叠加结果上比对落点。下面按可… · 2026/9/26 19:04:38
TeamAI-CLI实战：构建团队级AI Agent中间层的关键与避坑 1. 先把一个常见的认知误区掰开：LLM、Agent、中间层到底各管哪一段1.1 DeepSeek是模型，不是Agent很多团队在讨论Agent的时候，会把"我们用DeepSeek"和"我们上了Agent"混为一谈。里有个关键概念必须拆清楚。DeepSeek、GPT、… · 2026/9/26 19:04:32
从样条到解析：样条面到二次曲面智能转换算法的技术路径与工程实践 在现代CAD/CAM/CAE系统中，非均匀有理B样条（NURBS）是构建几何模型的行业通用方法。其核心优势在于能够以统一的数学形式表达从自由曲面到精确解析曲面的多种形状，NURBS方法已成为自由曲线曲面形状表示方面事实上的标准，… · 2026/9/26 19:04:32
完成同样任务：比以往更耗时、费token 我发现了一个非常不友好的变化趋势，使用workbuddy 及新的LLM，完成同样的修改模板，需要等待更久、更费token
低效率、高开销
跟以前很快就能解决问题完全不同了。
——是现在考虑问题更周到了，还是故意更浪费token多收费࿱… · 2026/9/26 19:04:32
Pandas数据分析入门：Series与DataFrame核心操作详解 1. 为什么数据分析绕不开Pandas刚接触Python数据分析那会儿，我最先装的是NumPy。数组运算确实快，但一到处理带标签的表格数据就浑身难受——想按列名取数得自己记索引，想按条件筛选得写一堆布尔运算，缺失值处理更是要手动循环。直… · 2026/9/26 19:04:26
WesCode编辑器实测：从安装配置到团队落地的完整指南 最近组里在传一个新编辑器 WesCode，说有同事把配置同步到公司内网后，处理一个中型 Go 服务时索引速度和补全响应明显快了不少。我一开始觉得又是“下一代编辑器”的常规炒作，直到自己跑了一遍才改变看法。WesCode 是一款面向本地开发场景的跨… · 2026/9/26 19:04:26
数据库课后习题答案别硬背：当测试用例集刷，效率翻倍 简介：万常选版《数据库原理与设计》课后习题答案资源，覆盖第2至6章及第9章，适合正在学习关系模型、数据库建模、关系数据理论与模式求精的本科生、自学者作为复习与自测材料。压缩包共7个文件，含3个doc参考答案、2个sql示例脚本、… · 2026/9/26 0:00:21
OpenClaw 替代品？Hermes Agent 踩坑实录：macOS 飞书接入 TaoToken 配置 /* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/9/26 0:00:40
向下兼容与向上兼容：接口设计中的兼容性策略与工程实践 一次版本升级事故，是很多团队绕不过去的坎。线上环境里，服务端明明已经上线了新版接口，老的移动端还在照着旧文档传参数。请求一到网关，校验直接拒绝，用户操作失败，客服群炸了锅，开发群里开始互… · 2026/9/26 0:00:46
