vault-para/100-project/Personal/AI/local litellm.md

---

📘 LiteLLM 配置指南：NewCli (AWS/Anthropic Proxy)

版本日期: 2025-12-26

适用场景: 对接自定义 Anthropic 代理（NewCli），解决路径拼接 (404)、参数不兼容 (400) 及防火墙拦截 (403) 问题。

1. 核心参数规范 (Critical Specs)

无论使用 UI 还是 YAML，必须严格遵守以下三条铁律：

1. Provider (提供商): 必须选 Anthropic。

   • 原因: 让 LiteLLM 自动处理 /v1/messages 路径拼接和 JSON 格式转换。

2. Base URL (基准地址): https://code.newcli.com/claude/aws

   • [!WARNING] 警告

   • 严禁在末尾加 /v1。LiteLLM 会自动追加，加了会导致双重路径 (/v1/v1) 报 404。

3. Model ID (模型名): claude-sonnet-4-5

   • 原因: 代理商白名单仅支持此 ID。

---

2. UI 配置方案 (推荐)

入口: LiteLLM UI (/ui) -> Models -> + Add Model

基础信息 (General Settings)

字段	填写内容	说明
Model Name	claude-sonnet	客户端调用的别名
Select Provider	Anthropic	⚠️ 必选
Litellm Model Name	claude-sonnet-4-5	真实模型 ID
API Base URL	https://code.newcli.com/claude/aws	⚠️ 末尾无 /v1
API Key	sk-ant-oat01...	填入完整 Key

高级参数 (LiteLLM Params / Metadata)

[!TIP] 关键步骤

在 JSON 输入框填入以下内容，用于解决参数兼容性和防火墙拦截。

JSON

{
  "drop_params": true,
  "extra_headers": {
    "anthropic-version": "2023-06-01",
    "User-Agent": "curl/7.68.0",
    "Authorization": "Bearer ${NEWCLI_API_KEY}" 
  },
  "no_verify_ssl": true
}

注：如果不使用变量，请在 Authorization 里直接填入 Bearer sk-ant...

---

3. YAML 文件配置方案 (IaC)

适用于 docker-compose 挂载配置。

YAML

model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      # ⚠️ 重点：Base URL 不带 /v1
      api_base: https://code.newcli.com/claude/aws
      # 建议使用环境变量
      api_key: os.environ/NEWCLI_API_KEY
      extra_headers:
        anthropic-version: "2023-06-01"
        # 伪装 UA 防拦截
        User-Agent: "curl/7.68.0"
        # 强制 Bearer 鉴权 (可选，视代理商严格程度)
        Authorization: "Bearer ${NEWCLI_API_KEY}"

general_settings:
  master_key: sk-1234
  database_url: postgresql://litellm:litellm@litellm-postgres:5432/litellm

litellm_settings:
  # ⚠️ 核心修复：丢弃不兼容参数（如 user, frequency_penalty），解决 400 错误
  drop_params: true
  set_verbose: true

---

4. 故障排查手册 (Troubleshooting)

状态码	错误类型	根本原因	解决方案
404	NotFoundError	路径重复	检查 api_base 是否多写了 /v1。应该让 LiteLLM 自动拼接。
400	BadRequest	参数冗余	LiteLLM 传了 OpenAI 专有参数给 Anthropic。需开启 drop_params: true。
403	Forbidden	WAF 拦截	缺少 User-Agent 伪装。需在 header 添加 "User-Agent": "curl/..."。
401	AuthError	鉴权失败	Key 错误或格式不对。尝试在 extra_headers 强制注入 Authorization: Bearer <key>。

---

5. 客户端调用示例

验证配置是否成功的标准命令（访问 LiteLLM 端口）：

Bash

curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "messages": [
      { "role": "user", "content": "Config Test: OK?" }
    ]
  }'