Claude Code + LiteLLM-Proxy + Langfuse 架构图
b1babo
2026年5月2日
2026年5月2日
Claude Code + LiteLLM-Proxy + Langfuse 架构图
系统架构流程图
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLAUDE CODE │
│ (AI 编程助手客户端) │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ HTTP Request
│ (Bearer: sk-litellm-xxx)
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ LITELLM PROXY │
│ (http://localhost:4000) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ config.yaml: │ │
│ │ - model_list: 定义可用模型 │ │
│ │ - master_key: 认证密钥 │ │
│ │ - database_url: PostgreSQL数据库 │ │
│ │ - callbacks: ["langfuse_otel", "langfuse"] │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ OpenTelemetry │
│ │ + Langfuse Callbacks │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PostgreSQL Database │ │
│ │ - 存储模型配置 │ │
│ │ - 存储回调配置 │ │
│ │ - 用户认证信息 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ 路由请求
│ (API Key + API Base)
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ AI PROVIDER │
│ (智谱AI / OpenAI / Anthropic 等) │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ ┌─────────────────────────────────────┐
│ │ LANGFUSE 追踪流程 │
│ │ (http://localhost:3000) │
│ │ │
│ │ ┌───────────────────────────────┐ │
│ │ │ 方法1: LiteLLM Callbacks │ │
│ │ │ - opentelemetry-distro │ │
│ │ │ - opentelemetry-exporter-otlp│ │
│ │ │ - 自动追踪API请求 │ │
│ │ └───────────────────────────────┘ │
│ │ │
│ │ ┌───────────────────────────────┐ │
│ │ │ 方法2: Claude Code Hook │ │
│ │ │ - ~/.claude/hooks/ │ │
│ │ │ - langfuse_hook.py │ │
│ │ │ - 在每次会话结束时触发 │ │
│ │ └───────────────────────────────┘ │
│ │ │
│ │ 追踪内容: │
│ │ - 请求/响应数据 │
│ │ - Token使用统计 │
│ │ - 性能指标 │
│ │ - 成本追踪 │
│ └─────────────────────────────────────┘
└─────────────────────────────────────────┘配置文件关系图
┌─────────────────────────────────────────────────────────────────────────────┐
│ ~/.claude.json (Claude Code 配置) │
│ { │
│ "env": { │
│ "ANTHROPIC_API_KEY": "sk-litellm-xxx" ────────┐ │
│ "ANTHROPIC_BASE_URL": "http://localhost:4000" │ │
│ "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-3-7-sonnet-20250219" │
│ } │
│ } │
└─────────────────────────────────────────────────────────────────────────────┘
│ │
│ │
▼ │
┌─────────────────────────────────────────────────────────────────────────────┤
│ config.yaml (LiteLLM Proxy 配置) │
│ model_list: │
│ - model_name: claude-3-7-sonnet-20250219 ◄──────────────────────────────┘
│ litellm_params:
│ api_key: real-provider-key
│ api_base: https://open.bigmodel.cn/api/anthropic
│ general_settings: │
│ master_key: sk-litellm-xxx (与 Claude Code API_KEY 匹配) │
│ database_url: postgresql://... │
│ litellm_settings: │
│ callbacks: ["langfuse_otel"] │
│ success_callback: ["langfuse"] │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ .env (环境变量) │
│ LITELLM_MASTER_KEY=sk-litellm-xxx │
│ UI_USERNAME=admin │
│ UI_PASSWORD=admin │
│ LANGFUSE_SECRET_KEY=sk-lf-xxxx │
│ LANGFUSE_PUBLIC_KEY=pk-lf-xxxx │
│ LANGFUSE_BASE_URL=http://localhost:3000 │
└─────────────────────────────────────────────────────────────────────────────┘数据流向图
用户请求 (Claude Code)
│
├─> 1. Claude Code 发送请求
│ 目标: http://localhost:4000/v1/chat/completions
│ 认证: Bearer sk-litellm-xxx
│
├─> 2. LiteLLM Proxy 接收请求
│ ├─ 验证 master_key
│ ├─ 查找 model_list 配置
│ └─ 提取真实 API Key 和 Base URL
│
├─> 3. Langfuse 追踪 (开始)
│ ├─ OpenTelemetry 自动记录请求
│ └─ Langfuse callback 捕获数据
│
├─> 4. 转发到 AI Provider
│ 目标: https://open.bigmodel.cn/api/anthropic
│ 认证: 真实 API Key
│
├─> 5. AI Provider 返回响应
│
├─> 6. Langfuse 追踪 (完成)
│ ├─ 记录响应数据
│ ├─ 统计 Token 使用
│ └─ 发送到 Langfuse 服务器
│
└─> 7. 返回给 Claude Code部署组件
┌─────────────────────────────────────────────────────────────────────────────┐
│ 运行时架构 │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Claude Code │ │ LiteLLM Proxy │ │ Langfuse │
│ │ │ │ │ │
│ Port: 动态 │───▶│ Port: 4000 │───▶│ Port: 3000 │
│ (本地客户端) │ │ (litellm -- │ │ (Docker/本地) │
│ │ │ config) │ │ │
└──────────────────┘ └──────────────────┘ └──────────────────┘
│
▼
┌──────────────────┐
│ PostgreSQL │
│ │
│ Port: 5433 │
│ (用户/模型数据) │
└──────────────────┘安装依赖关系
litellm-proxy/
├── litellm[proxy] # 核心代理服务器
├── opentelemetry-distro # OpenTelemetry 分布
├── opentelemetry-exporter-otlp # OTLP 导出器
├── prisma # 数据库 ORM
└── langfuse # Langfuse Python SDK
评论