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