133 lines
3.6 KiB
Markdown
133 lines
3.6 KiB
Markdown
|
|
|
|
---
|
|
|
|
# 📘 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?" }
|
|
]
|
|
}'
|
|
```
|
|
|