aliyun-model-proxy/docs/usage.md

使用说明

这个项目是一个本地 DashScope Anthropic 兼容反代服务。客户端只需要配置一个本地 URL 和一个代理 key，真实 DashScope key 和模型池都放在服务端。

1. 安装依赖

pnpm install

运行时依赖不包含原生编译模块，Windows 上首次安装不需要额外安装 C++ 编译环境。

2. 配置 .env

复制配置模板：

cp .env.example .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. 初始化状态文件

启动服务时会自动创建状态文件。

也可以手动初始化：

pnpm build
node dist/index.js

看到服务启动成功后按 Ctrl+C 停止即可。状态文件默认会生成在：

data/proxy-state.json

状态文件结构见：

docs/state-file.md

4. 启动服务

开发模式：

pnpm dev

生产模式：

pnpm build
pnpm start

启动成功后会看到类似日志：

[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. 客户端调用

本地代理地址：

http://localhost:3300

Anthropic Messages 接口：

http://localhost:3300/v1/messages

请求头可以用二选一：

Authorization: Bearer sk-001

或：

x-api-key: sk-001

测试请求：

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 接口：

http://localhost:3300/v1/chat/completions

OpenAI-compatible base URL：

http://localhost:3300/v1

测试请求：

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 风格模型列表：

curl http://localhost:3300/v1/models \
  -H "Authorization: Bearer sk-001"

本服务端只是反代转发，使用 Node 原生 fetch 即可，不需要安装 openai SDK。openai SDK 是客户端接入时才需要的。

6. Pi CLI 接入

Pi CLI 的 provider 已配置为：

local-dashscope-proxy

指向：

http://127.0.0.1:3300

默认使用：

provider: local-dashscope-proxy
model: qwen3.7-max

使用前先启动代理服务：

pnpm dev

然后运行：

pi

也可以显式指定：

pi --provider local-dashscope-proxy --model qwen3.7-max

查看 Pi 是否识别 provider：

pi --list-models local --offline

如果想让 Pi CLI 按 OpenAI Chat Completions 协议接入，可以在 ~/.pi/agent/models.json 增加类似 provider：

{
  "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. 查看服务状态

健康检查：

curl http://localhost:3300/health

模型池状态：

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. 常见操作

重新生成状态文件：

rm data/proxy-state.json
pnpm dev

只想清空冷却状态，也可以删除状态文件后重新启动。注意这会丢失所有历史冷却和失败计数。

查看状态文件：

data/proxy-state.json

状态文件和自动备份文件不需要提交。