oy-paddy
339 lines
6.9 KiB
Markdown
339 lines
6.9 KiB
Markdown
# 使用说明
|
||
|
||
这个项目是一个本地 DashScope Anthropic 兼容反代服务。客户端只需要配置一个本地 URL 和一个代理 key，真实 DashScope key 和模型池都放在服务端。
|
||
|
||
## 1. 安装依赖
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
运行时依赖不包含原生编译模块，Windows 上首次安装不需要额外安装 C++ 编译环境。
|
||
|
||
## 2. 配置 .env
|
||
|
||
复制配置模板：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
核心配置：
|
||
|
||
```env
|
||
PORT=3300
|
||
|
||
PROXY_API_KEY=sk-001
|
||
|
||
DASHSCOPE_API_KEYS=sk-key-1,sk-key-2,sk-key-3
|
||
UPSTREAM_BASE_URL=https://dashscope.aliyuncs.com/apps/anthropic
|
||
OPENAI_UPSTREAM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||
|
||
MODEL_IDS=qwen3.7-max,qwen-plus,qwen-max
|
||
MODEL_COOLDOWN_SECONDS=2592000
|
||
|
||
STATE_PATH=./data/proxy-state.json
|
||
UPSTREAM_AUTH_MODE=authorization
|
||
CORS_ORIGIN=*
|
||
```
|
||
|
||
说明：
|
||
|
||
| 配置 | 说明 |
|
||
| --- | --- |
|
||
| `PORT` | 本地服务端口。你当前给 Pi CLI 用的是 `3300`。 |
|
||
| `PROXY_API_KEY` | 客户端调用本地代理时使用的 key。 |
|
||
| `DASHSCOPE_API_KEYS` | 多个真实 DashScope API Key，英文逗号分隔。 |
|
||
| `UPSTREAM_BASE_URL` | DashScope Anthropic 兼容接口上游地址。 |
|
||
| `OPENAI_UPSTREAM_BASE_URL` | DashScope OpenAI Chat Completions 兼容接口上游地址。 |
|
||
| `MODEL_IDS` | 所有 key 共用的模型 ID 列表，英文逗号分隔。 |
|
||
| `MODEL_COOLDOWN_SECONDS` | 触发免费额度耗尽后冷却多久。当前默认 `2592000` 秒，也就是 30 天。 |
|
||
| `STATE_PATH` | JSON 状态文件路径。用于保存冷却状态和调度游标。 |
|
||
|
||
## 3. 初始化状态文件
|
||
|
||
启动服务时会自动创建状态文件。
|
||
|
||
也可以手动初始化：
|
||
|
||
```bash
|
||
pnpm build
|
||
node dist/index.js
|
||
```
|
||
|
||
看到服务启动成功后按 `Ctrl+C` 停止即可。状态文件默认会生成在：
|
||
|
||
```text
|
||
data/proxy-state.json
|
||
```
|
||
|
||
状态文件结构见：
|
||
|
||
```text
|
||
docs/state-file.md
|
||
```
|
||
|
||
## 4. 启动服务
|
||
|
||
开发模式：
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
生产模式：
|
||
|
||
```bash
|
||
pnpm build
|
||
pnpm start
|
||
```
|
||
|
||
启动成功后会看到类似日志：
|
||
|
||
```text
|
||
[proxy] listening on http://localhost:3300
|
||
[proxy] upstream base: https://dashscope.aliyuncs.com/apps/anthropic
|
||
[proxy] openai upstream base: https://dashscope.aliyuncs.com/compatible-mode/v1
|
||
[proxy] api keys loaded: 3
|
||
[proxy] models per key: 3
|
||
[proxy] applied model ids:
|
||
[proxy] - qwen3.7-max
|
||
[proxy] - qwen-plus
|
||
[proxy] - qwen-max
|
||
[proxy] reminder: 请在 DashScope/百炼控制台为以上模型开启“模型用完即停”。
|
||
[proxy] state file: ./data/proxy-state.json
|
||
```
|
||
|
||
## 5. 客户端调用
|
||
|
||
本地代理地址：
|
||
|
||
```text
|
||
http://localhost:3300
|
||
```
|
||
|
||
Anthropic Messages 接口：
|
||
|
||
```text
|
||
http://localhost:3300/v1/messages
|
||
```
|
||
|
||
请求头可以用二选一：
|
||
|
||
```http
|
||
Authorization: Bearer sk-001
|
||
```
|
||
|
||
或：
|
||
|
||
```http
|
||
x-api-key: sk-001
|
||
```
|
||
|
||
测试请求：
|
||
|
||
```bash
|
||
curl http://localhost:3300/v1/messages \
|
||
-H "Authorization: Bearer sk-001" \
|
||
-H "Content-Type: application/json" \
|
||
-H "anthropic-version: 2023-06-01" \
|
||
-d '{
|
||
"model": "client-model-will-be-overwritten",
|
||
"max_tokens": 256,
|
||
"messages": [
|
||
{
|
||
"role": "user",
|
||
"content": "你好"
|
||
}
|
||
]
|
||
}'
|
||
```
|
||
|
||
请求体里的 `model` 会被代理覆盖成当前可用模型。
|
||
|
||
OpenAI Chat Completions 接口：
|
||
|
||
```text
|
||
http://localhost:3300/v1/chat/completions
|
||
```
|
||
|
||
OpenAI-compatible base URL：
|
||
|
||
```text
|
||
http://localhost:3300/v1
|
||
```
|
||
|
||
测试请求：
|
||
|
||
```bash
|
||
curl http://localhost:3300/v1/chat/completions \
|
||
-H "Authorization: Bearer sk-001" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "client-model-will-be-overwritten",
|
||
"messages": [
|
||
{
|
||
"role": "user",
|
||
"content": "你好"
|
||
}
|
||
],
|
||
"stream": true
|
||
}'
|
||
```
|
||
|
||
查看 OpenAI 风格模型列表：
|
||
|
||
```bash
|
||
curl http://localhost:3300/v1/models \
|
||
-H "Authorization: Bearer sk-001"
|
||
```
|
||
|
||
本服务端只是反代转发，使用 Node 原生 `fetch` 即可，不需要安装 `openai` SDK。`openai` SDK 是客户端接入时才需要的。
|
||
|
||
## 6. Pi CLI 接入
|
||
|
||
Pi CLI 的 provider 已配置为：
|
||
|
||
```text
|
||
local-dashscope-proxy
|
||
```
|
||
|
||
指向：
|
||
|
||
```text
|
||
http://127.0.0.1:3300
|
||
```
|
||
|
||
默认使用：
|
||
|
||
```text
|
||
provider: local-dashscope-proxy
|
||
model: qwen3.7-max
|
||
```
|
||
|
||
使用前先启动代理服务：
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
然后运行：
|
||
|
||
```bash
|
||
pi
|
||
```
|
||
|
||
也可以显式指定：
|
||
|
||
```bash
|
||
pi --provider local-dashscope-proxy --model qwen3.7-max
|
||
```
|
||
|
||
查看 Pi 是否识别 provider：
|
||
|
||
```bash
|
||
pi --list-models local --offline
|
||
```
|
||
|
||
如果想让 Pi CLI 按 OpenAI Chat Completions 协议接入，可以在 `~/.pi/agent/models.json` 增加类似 provider：
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"local-dashscope-openai-proxy": {
|
||
"baseUrl": "http://127.0.0.1:3300/v1",
|
||
"api": "openai-completions",
|
||
"apiKey": "sk-001",
|
||
"compat": {
|
||
"supportsDeveloperRole": false,
|
||
"supportsReasoningEffort": true,
|
||
"maxTokensField": "max_tokens",
|
||
"thinkingFormat": "qwen"
|
||
},
|
||
"models": [
|
||
{
|
||
"id": "qwen3.7-max",
|
||
"name": "Qwen 3.7 Max (Local OpenAI Proxy)",
|
||
"reasoning": true,
|
||
"input": ["text", "image"],
|
||
"contextWindow": 131072,
|
||
"maxTokens": 32768,
|
||
"thinkingLevelMap": {
|
||
"off": null,
|
||
"minimal": "low",
|
||
"low": "low",
|
||
"medium": "medium",
|
||
"high": "high",
|
||
"xhigh": "high"
|
||
},
|
||
"cost": {
|
||
"input": 0,
|
||
"output": 0,
|
||
"cacheRead": 0,
|
||
"cacheWrite": 0
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 7. 查看服务状态
|
||
|
||
健康检查：
|
||
|
||
```bash
|
||
curl http://localhost:3300/health
|
||
```
|
||
|
||
模型池状态：
|
||
|
||
```bash
|
||
curl http://localhost:3300/models/status \
|
||
-H "Authorization: Bearer sk-001"
|
||
```
|
||
|
||
返回中重要字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `totalKeys` | 当前加载的 DashScope key 数量。 |
|
||
| `modelsPerKey` | 每个 key 下的模型数量。 |
|
||
| `totalSlots` | key+model 总组合数。 |
|
||
| `availableSlots` | 当前可用的 key+model 组合数。 |
|
||
| `models[].keyHash` | key hash 前缀，用于区分 key，不是明文 key。 |
|
||
| `models[].id` | 模型 ID。 |
|
||
| `models[].available` | 当前组合是否可用。 |
|
||
| `models[].cooldownUntil` | 冷却截止时间。 |
|
||
| `models[].failureCount` | 累计触发免费额度耗尽次数。 |
|
||
|
||
## 8. 切换规则
|
||
|
||
服务按这个规则自动切换：
|
||
|
||
1. 优先使用当前 key。
|
||
2. 当前 key 下某个模型触发免费额度耗尽 403，只冷却这个 key+model。
|
||
3. 继续尝试当前 key 的下一个模型。
|
||
4. 当前 key 下所有模型都冷却后，才切换到下一个 key。
|
||
5. 所有 key+model 都冷却时，返回 `503`。
|
||
|
||
## 9. 常见操作
|
||
|
||
重新生成状态文件：
|
||
|
||
```bash
|
||
rm data/proxy-state.json
|
||
pnpm dev
|
||
```
|
||
|
||
只想清空冷却状态，也可以删除状态文件后重新启动。注意这会丢失所有历史冷却和失败计数。
|
||
|
||
查看状态文件：
|
||
|
||
```text
|
||
data/proxy-state.json
|
||
```
|
||
|
||
状态文件和自动备份文件不需要提交。
|