Claude Code + LiteLLM Proxy + Langfuse 完整安装指南

Claude Code + LiteLLM Proxy + Langfuse 完整安装指南

本指南将帮助您搭建一个完整的 AI 代理系统，实现 Claude Code 通过 LiteLLM Proxy 访问多个 AI 提供商，并使用 Langfuse 进行完整的请求追踪。

🎯 系统架构概览

Claude Code → LiteLLM Proxy → AI Providers (智谱AI/OpenAI等)
                  ↓
            Langfuse (追踪与监控)

📋 前置要求

• Python 3.11+
• PostgreSQL 数据库
• Docker (用于 Langfuse)
• 基本的 Linux 命令行知识

🔧 安装步骤

第一步：安装系统依赖

# 确保使用 Python 3.11+
python --version

# 安装 uv 包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh

第二步：创建项目并安装依赖

# 创建项目目录
mkdir litellm-proxy
cd litellm-proxy

# 初始化 uv 项目
uv init

# 安装所需依赖
uv add litellm[proxy] opentelemetry-distro opentelemetry-exporter-otlp prisma langfuse

第三步：生成 Prisma 客户端

# 查找 schema.prisma 位置
uv pip show litellm -f | grep schema.prisma | awk '{print $NF}'

# 根据得到的路径生成客户端（示例路径，请根据实际结果调整）
prisma generate --schema .venv/lib/python3.11/site-packages/litellm/proxy/schema.prisma

第四步：配置环境变量

创建 .env 文件：

# LiteLLM Proxy 配置
LITELLM_MASTER_KEY="sk-litellm-proxy"  # 代理服务器主密钥
UI_USERNAME=admin                      # Web UI 用户名
UI_PASSWORD=admin                      # Web UI 密码

# 数据库配置
DATABASE_URL="postgresql://postgres:[email protected]:5433/litellm-proxy"

# Langfuse 配置
LANGFUSE_SECRET_KEY="sk-lf-your-secret-key"
LANGFUSE_PUBLIC_KEY="pk-lf-your-public-key"
LANGFUSE_BASE_URL="http://localhost:3000"

# 功能开关
STORE_MODEL_IN_DB='True'  # 允许在 UI 界面添加模型和回调

第五步：配置 LiteLLM Proxy

创建 config.yaml 文件：

# 模型列表配置
model_list:
  - model_name: claude-3-7-sonnet-20250219
    litellm_params:
      model: claude-3-7-sonnet-20250219
      api_key: your-actual-provider-api-key
      api_base: https://open.bigmodel.cn/api/anthropic

  # 可以添加更多模型
  # - model_name: gpt-4
  #   litellm_params:
  #     model: gpt-4
  #     api_key: your-openai-api-key

# 通用设置
general_settings:
  master_key: sk-litellm-proxy  # 与 .env 中的 LITELLM_MASTER_KEY 一致
  database_url: "postgresql://postgres:[email protected]:5433/litellm-proxy"

# LiteLLM 设置
litellm_settings:
  callbacks: ["langfuse_otel"]        # OpenTelemetry 集成
  success_callback: ["langfuse"]      # Langfuse 回调

第六步：启动 Langfuse 服务

参考https://langfuse.com/self-hosting/deployment/docker-compose

第七步：启动 LiteLLM Proxy

# 启动代理服务器
litellm --config ./config.yaml --detailed_debug

# 或使用配置文件指定端口
litellm --config ./config.yaml --port 4000 --detailed_debug

第八步：配置 Claude Code

编辑 ~/.claude.json 文件：

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-litellm-proxy",
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-3-7-sonnet-20250219",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-3-7-sonnet-20250219",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-3-7-sonnet-20250219"
  }
}

第九步：配置 Claude Code Langfuse 集成 (可选)

新增~/.claude/hooks/langfuse_hook.py 参考https://langfuse.com/integrations/other/claude-code

编辑 ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/root/litellm-proxy/.venv/bin/python ~/.claude/hooks/langfuse_hook.py"
          }
        ]
      }
    ]
  },
  "env": {
    "TRACE_TO_LANGFUSE": "true",
    "LANGFUSE_PUBLIC_KEY": "pk-lf-your-public-key",
    "LANGFUSE_SECRET_KEY": "sk-lf-your-secret-key",
    "LANGFUSE_BASE_URL": "http://localhost:3000"
  }
}

🧪 测试验证

测试 LiteLLM Proxy

# 测试代理服务是否正常工作
curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-litellm-proxy" \
  -d '{ 
    "model": "claude-3-7-sonnet-20250219",
    "messages": [{"role": "user", "content": "Hello, how are you?"}]
  }'

预期响应：

{
  "id": "generated-id",
  "created": 1234567890,
  "model": "claude-3-7-sonnet-20250219",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Hello! I'm doing well, thank you for asking!"
    }
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}

测试 Claude Code 集成

1. 重启 Claude Code
2. 发送测试消息
3. 检查 Langfuse UI (http://localhost:3000) 是否接收到追踪数据

📊 监控与调试

查看 LiteLLM 日志

# 日志会显示在终端
# 关注以下信息：
# - 请求路由
# - Token 使用情况
# - Langfuse 回调状态

访问 Web UI

• LiteLLM UI: http://localhost:4000/ui
• Langfuse UI: http://localhost:3000

常见问题排查

1. 连接被拒绝

   # 检查服务是否运行
   curl http://localhost:4000/health
   
   # 检查端口占用
   netstat -tulpn | grep 4000

2. 认证失败

   # 确认密钥一致性
   echo $LITELLM_MASTER_KEY
   grep master_key config.yaml

3. Langfuse 无数据

   # 检查 Langfuse 连接
   curl http://localhost:3000/health
   
   # 验证回调配置
   grep callbacks config.yaml

🔒 安全建议

1. 密钥管理
   • 使用强密钥
   • 定期轮换密钥
   • 不要在代码中硬编码密钥
2. 网络安全
   • 仅在可信网络中使用
   • 考虑使用 HTTPS/TLS
   • 配置防火墙规则
3. 访问控制
   • 限制 UI 访问权限
   • 使用强密码
   • 定期审计访问日志

📞 获取帮助

• LiteLLM 文档: https://docs.litellm.ai/
• Langfuse 文档: https://langfuse.com/
• Claude Code 文档: https://claude.com/claude-code