企业官网建设流程全解析

ODS接入Langfuse：给本地AI服务器装上可观测性引擎

【免费下载链接】ODSTurn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation.项目地址: https://gitcode.com/GitHub_Trending/dr/ODS

ODS可以把 PC、Mac 或 Linux 变成一台私有 AI 服务器，而 Langfuse 可观测性扩展 让每一次 LLM 调用都有迹可循——请求、Token、延迟、模型版本，全部自动记录，无需改动任何业务代码。本文带你用最少的步骤，为本地 AI 栈装上这套开源 Tracing 引擎。

为什么本地 AI 服务器需要可观测性

当你的 AI 服务器上跑着 LiteLLM、Open WebUI、n8n 工作流和多个 Agent 时，一个常见问题是：输出质量变差了，但不知道是哪个模型、哪条 Prompt 出的问题。

手动翻容器日志低效且不可靠。Langfuse 作为开源 LLM 观测平台，提供三大核心能力：

• 📊完整调用链（Traces）：每次 LLM 请求的输入、输出、延迟、Token 数、所用模型一目了然
• ⭐评估（Evaluations）：对调用结果打分数，手动或程序化跟踪质量变化趋势
• ✏️Prompt 管理：在界面中版本化 Prompt 模板并做 A/B 测试

💡 在多 Agent 场景下，观测平台几乎是刚需。ODS 官方模板 multi-agent-laboratory.yaml 就注明：Langfuse 用于 "debugging agent loops"。

一键启用：两条命令完成部署

Langfuse 在 ODS 中是默认关闭的可选扩展，启用只需一行命令：

ods enable langfuse

或者在安装阶段直接带上参数：

./install.sh --langfuse

扩展的完整定义见 compose.yaml.disabled（启用后自动重命名为compose.yaml生效），服务元数据则定义在 manifest.yaml 中。

启用后，Langfuse 界面运行在http://localhost:3006，端口可通过.env中的LANGFUSE_PORT修改。

首次启动的小提示

Langfuse 由 6 个容器组成（Web、Worker、PostgreSQL、ClickHouse、Redis、MinIO），全部运行在隔离的langfuse-internal内部网络中。ClickHouse 首次启动需要约 90 秒初始化，请耐心等待所有容器变为 healthy 状态。

零配置打通 LiteLLM：Traces 自动上报

这是 ODS 集成 Langfuse 最优雅的地方——不需要修改任何 LiteLLM 配置，也不需要改应用代码。

原理很简单：

1. 安装器自动生成项目密钥对（LANGFUSE_PROJECT_PUBLIC_KEY/SECRET_KEY），写入.env
2. 扩展的 compose overlay 在启用时，自动把这两个密钥和LANGFUSE_HOST注入 LiteLLM 容器
3. LiteLLM 入口脚本检测到LANGFUSE_ENABLED=true后，自动注册langfuse回调

LiteLLM 侧的回调注入逻辑可以查看 litellm/compose.yaml。也就是说：开关一打开，所有经过 LiteLLM 的调用就自动出现在 Langfuse 面板里。

数据完全留在本地：私有化数据栈

担心 Trace 数据泄露？在 ODS 中，Langfuse 的所有数据都存储在本地磁盘，且与其他扩展完全隔离：

所有密码和密钥（数据库口令、加密密钥等）都由安装器自动生成并保存在.env，无需手动设置。

值得一提的是，post_install.sh 钩子会在 Linux 原生 Docker 环境自动修正数据目录的 uid 归属，避免 PostgreSQL/ClickHouse 因权限问题初始化失败——macOS 和 WSL2 用户无需关心这一步。

常见问题快速排查

① 界面没有 Trace？确认.env中LANGFUSE_ENABLED=true，然后重启 LiteLLM：

docker compose up -d --force-recreate litellm docker compose logs litellm | grep -i langfuse

② 服务起不来？逐个检查 6 个容器的健康状态：

docker compose ps langfuse langfuse-worker langfuse-postgres

③ 登录不进去？检查.env中的LANGFUSE_INIT_USER_EMAIL/LANGFUSE_INIT_USER_PASSWORD（默认邮箱admin@ods.local）。修改凭证后需重建容器生效。

④ 内存占用偏高？ClickHouse 是最大消耗者（默认上限 2 GB），可在 compose 文件的deploy.resources.limits中调整。

把它放进你的模板

ODS 提供了多个官方模板，开箱即用地包含 Langfuse：

• llm-platform.yaml：LLM 平台全家桶（LiteLLM + Langfuse + Token-Spy + LibreChat + n8n）
• ml-data-workshop.yaml：机器学习数据工作坊
• onboarding-full-stack.yaml：全栈入门方案

完整扩展目录可参阅 extensions/CATALOG.md。

总结

用一行ods enable langfuse，你就拥有了：

• ✅ 全量 LLM 调用链追踪，问题定位从"大海捞针"到"按图索骥"
• ✅ Prompt 版本管理与 A/B 测试，质量改进有据可依
• ✅ 评估体系，让 AI 应用的质量可度量、可追踪
• ✅ 数据 100% 本地化，隐私安全无忧

给本地 AI 服务器装上 Langfuse 观测引擎，是你从"能跑起来"迈向"跑得明白"的关键一步。

【免费下载链接】ODSTurn your PC, Mac, or Linux box into an AI server. LLM inference, chat UI, voice, agents, workflows, RAG, and image generation.项目地址: https://gitcode.com/GitHub_Trending/dr/ODS