Langfuse LLM可观测性平台部署
日期: 2026-02-17 08:30-11:00
协调人: Coco🐳
触发: William批准AI OS基础设施第7层（可观测性）建设
执行概要
成功部署Langfuse v3.153.0作为AI OS的LLM可观测性中枢，并集成到model_dispatcher和crew_manager两个核心模块。实现了从"模型调用黑箱"到"全链路可追踪"的跨越。
1. Docker部署（6容器）
基础设施
| 服务 |
镜像 |
端口 |
用途 |
| PostgreSQL 17 |
postgres:17 |
5432 |
主数据库 |
| ClickHouse |
clickhouse/clickhouse-server |
8123/9000 |
分析数据库 |
| Redis 7 |
redis:7 |
6379 |
缓存/队列 |
| MinIO |
minio/minio |
9090 |
对象存储 |
| Langfuse Web |
langfuse/langfuse |
3000 |
Web UI + API |
| Langfuse Worker |
langfuse/langfuse-worker |
3030 |
后台处理 |
部署过程
- Docker镜像拉取（中国网络，分批拉取）
- 首次启动发现DATABASE_URL密码不匹配（Prisma P1000错误）
- 修复.env中DATABASE_URL与POSTGRES_PASSWORD对齐
docker compose down -v 清除旧卷 + docker compose up -d 全新启动- 6/6容器全部healthy
关键配置
- 自动初始化: 通过
LANGFUSE_INIT_*环境变量预建org/project/user，免手动注册
- 访问地址: http://localhost:3000
- 登录凭证: william@hivecosm.com / hivecosm2026
- API Keys: pk-lf-hivecosm-aios / sk-lf-hivecosm-aios
- 遥测关闭:
TELEMETRY_ENABLED=false（数据不出本机）
2. SDK集成（Python v3.14.2）
集成点A: model_dispatcher.py（跨模型调度器）
- 位置: 模块级初始化 +
dispatch_to()方法内
- 追踪类型: Generation（每次模型调用记录input/output/usage/latency）
- API模式: v3
start_observation(as_type='generation') + .update() + .end()
集成点B: crews/crew_manager.py（Crew编排器）
- 位置:
CrewAIExecutor.execute() + ClaudeExecutor.execute()
- 追踪类型: Span（记录Crew任务执行全过程）
- 元数据: executor类型、assignee、task_id
SDK v3 API要点（经验）
| v2 API (已废弃) |
v3 API (正确) |
lf.trace() |
已移除 |
lf.generation() |
lf.start_observation(as_type='generation') |
gen.end(output=...) |
gen.update(output=...) 然后 gen.end() |
usage={...} |
usage_details={...} |
3. 端到端验证
测试执行
| 模型 |
延迟 |
Tokens |
结果 |
| glm-4-flash |
1006ms |
28 |
✅ |
| deepseek-chat |
1597ms |
50 |
✅ |
API验证
GET /api/public/traces → 2 Traces
GET /api/public/observations → 2 Observations (type=GENERATION)
UI验证
William登录Langfuse UI确认可看到完整的Trace记录，包括：
- 模型名称、provider
- 输入输出内容
- Token使用量
- 延迟数据
4. 架构意义
AI OS 7层基础设施（更新后）
| 层级 |
组件 |
状态 |
| L1 配置层 |
CLAUDE.md + 员工花名册 |
✅ |
| L2 记忆层 |
memory_flush + embedding_indexer |
✅ |
| L3 路由层 |
LiteLLM网关 + model_dispatcher |
✅ |
| L4 编排层 |
CrewAI + crew_manager |
✅ |
| L5 执行层 |
agent_executor + Claude CLI |
✅ |
| L6 通信层 |
MessageBus + WebSocket |
✅ |
| L7 可观测层 |
Langfuse v3.153.0 |
✅ 新增 |
商业价值
- 专利素材: 可为P0-003（跨模型调度专利）提供真实运行数据截图
- 成本优化: 可精确追踪每个模型的Token消耗，优化路由策略
- 质量监控: 可对比不同模型在同一任务上的输出质量
- 客户演示: Langfuse Dashboard作为AI OS产品能力的可视化证据
5. 文件变更
| 文件 |
变更 |
行数变化 |
langfuse/.env |
修复DATABASE_URL + S3凭证 |
+2行 |
model_dispatcher.py |
新增Langfuse Generation追踪 |
+30行 |
crews/crew_manager.py |
新增Langfuse Span追踪 |
+40行 |
6. 启停命令
# 启动Langfuse
cd "日记/数字员工团队/09-虚拟办公区系统/langfuse"
docker compose up -d
# 停止Langfuse
docker compose down
# 查看状态
docker compose ps
# 健康检查
curl http://localhost:3000/api/public/health
7. 待优化（P2）
- Trace关联: 将model_dispatcher的Generation与crew_manager的Span关联为完整Trace链
- Prompt版本管理: 利用Langfuse的Prompt Management功能管理System Prompt版本
- 评估数据集: 建立标准化评估数据集，量化模型输出质量
- 告警规则: 设置Token超额、延迟异常等告警
🐳 Coco | 2026-02-17 11:00