feat(ai/gateway): 将LiteLLM网关从DashScope切换到NewAPI

- 添加新的litellm.local.yaml配置文件，支持NewAPI OpenAI兼容接口
- 修改compose.yaml使用litellm.local.yaml作为默认配置
- 更新环境变量配置，新增NEWAPI_API_BASE和NEWAPI_KEY
- 在文档中更新配置说明和环境变量描述
- 修改模型路由配置，添加显式模型注册和通配符兜底路由
- 添加模型查询相关的API示例和说明

BREAK

Author: mudssky

ai/gateway/.gitignore

@@ -0,0 +1 @@
+*.local.yaml

ai/gateway/litellm/.env.example

@@ -1,6 +1,12 @@
+# LiteLLM 镜像标签；开发环境默认跟随上游主线镜像。
 LITELLM_IMAGE=docker.litellm.ai/berriai/litellm:main-latest
+# LiteLLM 对宿主机暴露的 HTTP 端口。
 LITELLM_HOST_PORT=34000
-DASHSCOPE_API_KEY=sk-xxxx
-DASHSCOPE_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
+# NewAPI OpenAI 兼容接口地址；建议保留到 `/v1`。
+NEWAPI_API_BASE=http://new-api.example.com/v1
+# NewAPI 上游鉴权密钥；LiteLLM 会透传它请求 `/chat/completions`、`/models` 等接口。
+NEWAPI_KEY=sk-newapi-dev-xxxx
+# LiteLLM 自身的网关密钥；客户端访问 LiteLLM 时使用这个 key。
 LITELLM_MASTER_KEY=sk-litellm-123456
+# LiteLLM 元数据数据库；未显式设置时 compose 会使用默认本地 PostgreSQL 地址。
 DATABASE_URL=postgresql://postgres:12345678@host.docker.internal:5432/litellm

ai/gateway/litellm/.env.production.example

@@ -1,7 +1,12 @@
 # 生产环境建议固定镜像版本，并通过反向代理暴露 HTTPS。
 LITELLM_IMAGE=docker.litellm.ai/berriai/litellm:main-latest
+# 建议只在内网暴露 LiteLLM 端口，对外由反向代理接管。
 LITELLM_HOST_PORT=34000
-DASHSCOPE_API_KEY=sk-prod-xxxx
-DASHSCOPE_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
+# 生产环境请改为实际 NewAPI 地址，并确保 LiteLLM 容器可访问。
+NEWAPI_API_BASE=https://new-api.internal.example.com/v1
+# 生产环境 NewAPI 密钥；建议由密钥管理系统注入。
+NEWAPI_KEY=sk-newapi-prod-change-me
+# LiteLLM 对外暴露的网关密钥；客户端通过它访问 LiteLLM。
 LITELLM_MASTER_KEY=sk-litellm-prod-change-me
+# 生产环境建议使用独立数据库账号，并限制到最小权限。
 DATABASE_URL=postgresql://litellm:change-me@postgres.internal:5432/litellm

ai/gateway/litellm/compose.yaml

@@ -8,14 +8,19 @@ services:
     environment:
       # LiteLLM 官方镜像会把 PORT 透传给内部 uvicorn 启动参数，未显式设置时会报错。
       PORT: "4000"
+      # 当前镜像需要显式提供配置文件路径；仅挂载 /app/config.yaml 并不会自动加载 model_list。
+      CONFIG_FILE_PATH: "/app/config.yaml"
       # 通过 compose 插值保留当前默认数据库地址；start.ps1 会在存在 .env.local 时传入 --env-file 以支持本地覆盖。
       DATABASE_URL: ${DATABASE_URL:-postgresql://postgres:12345678@host.docker.internal:5432/litellm}
-      # LiteLLM 运行时会从容器环境变量读取这些值，再由 qwen.yaml 中的 os.environ/... 引用。
+      # 当前本地配置走 NewAPI OpenAI 兼容接口；变量必须显式注入容器，LiteLLM 才能解析 os.environ/...。
+      NEWAPI_API_BASE: ${NEWAPI_API_BASE:-}
+      NEWAPI_KEY: ${NEWAPI_KEY:-}
+      # 保留旧变量，避免切回 qwen.yaml 等历史配置时还要额外补环境变量。
       DASHSCOPE_API_KEY: ${DASHSCOPE_API_KEY:-}
       DASHSCOPE_API_BASE: ${DASHSCOPE_API_BASE:-https://dashscope.aliyuncs.com/compatible-mode/v1}
       LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:-}
     volumes:
-      - ./qwen.yaml:/app/config.yaml:ro
+      - ./litellm.local.yaml:/app/config.yaml:ro
     extra_hosts:
       # 在 Linux Docker Engine 场景补齐宿主机别名，保持默认 DATABASE_URL 可用。
       - "host.docker.internal:host-gateway"

ai/gateway/litellm/litellm.md

@@ -1,15 +1,16 @@
 # LiteLLM 网关说明
 
-这个目录用于启动一个基于 LiteLLM Proxy 的生产级 Qwen 网关，默认直连阿里百炼的 OpenAI 兼容接口。
+这个目录用于启动一个基于 LiteLLM Proxy 的 OpenAI 兼容网关，当前默认通过 NewAPI 转发请求到上游模型服务。
 
 相关文件职责如下：
 
-- `qwen.yaml`：LiteLLM 生产配置，定义主模型、降级模型、限流、重试和超时策略。
+- `litellm.local.yaml`：本地默认配置，定义 LiteLLM 的 wildcard 路由与上游 NewAPI 连接方式。
+- `qwen.yaml`：历史示例配置，保留了固定模型与降级策略写法，可作为按模型显式映射时的参考。
 - `compose.yaml`：LiteLLM 容器模板，定义镜像、端口、挂载和默认环境变量。
 - `start.ps1`：统一入口，封装常用 `docker compose` 操作。
 - `.env.example`：开发环境变量示例。
 - `.env.production.example`：生产环境变量示例。
-- `.env.local`：本地私有环境变量，保存 `DASHSCOPE_API_KEY`、`DASHSCOPE_API_BASE`、`LITELLM_MASTER_KEY`、可选 `DATABASE_URL`。
+- `.env.local`：本地私有环境变量，保存 `NEWAPI_API_BASE`、`NEWAPI_KEY`、`LITELLM_MASTER_KEY`、可选 `DATABASE_URL`。
 
 ## 环境变量
 
@@ -18,8 +19,8 @@
 ```dotenv
 LITELLM_IMAGE=docker.litellm.ai/berriai/litellm:main-latest
 LITELLM_HOST_PORT=34000
-DASHSCOPE_API_KEY=sk-xxxx
-DASHSCOPE_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
+NEWAPI_API_BASE=http://new-api.example.com/v1
+NEWAPI_KEY=sk-newapi-dev-xxxx
 LITELLM_MASTER_KEY=sk-litellm-123456
 DATABASE_URL=postgresql://postgres:12345678@host.docker.internal:5432/litellm
 ```
@@ -28,8 +29,8 @@ DATABASE_URL=postgresql://postgres:12345678@host.docker.internal:5432/litellm
 
 - `LITELLM_IMAGE`：LiteLLM 镜像，可用于生产环境固定到经过验证的标签。
 - `LITELLM_HOST_PORT`：宿主机暴露端口，默认 `34000`。
-- `DASHSCOPE_API_KEY`：阿里百炼 API Key。
-- `DASHSCOPE_API_BASE`：阿里百炼 OpenAI 兼容接口地址；中国内地默认可用 `https://dashscope.aliyuncs.com/compatible-mode/v1`。
+- `NEWAPI_API_BASE`：NewAPI 的 OpenAI 兼容接口地址，建议带上 `/v1`。
+- `NEWAPI_KEY`：LiteLLM 转发到 NewAPI 时使用的上游密钥。
 - `LITELLM_MASTER_KEY`：LiteLLM Proxy 对外暴露的网关密钥。
 - `DATABASE_URL`：LiteLLM 的数据库连接串；如果未配置，会回退到默认的宿主机 PostgreSQL 地址。
 
@@ -100,15 +101,51 @@ OpenAI 兼容接口示例：
 curl http://127.0.0.1:34000/v1/chat/completions `
   -H "Content-Type: application/json" `
   -H "Authorization: Bearer sk-litellm-123456" `
-  -d "{\"model\":\"qwen-chat\",\"messages\":[{\"role\":\"user\",\"content\":\"你好\"}]}"
+  -d "{\"model\":\"gemini-2.5-flash\",\"messages\":[{\"role\":\"user\",\"content\":\"你好\"}]}"
 ```
 
+## 模型查询
+
+如果你想查看 LiteLLM 当前暴露的路由名，可调用：
+
+```powershell
+curl "http://127.0.0.1:34000/models?return_wildcard_routes=true" `
+  -H "x-litellm-api-key: sk-litellm-123456"
+```
+
+当前 `litellm.local.yaml` 默认显式注册了 `gpt-5.4`、`gemini-3.1-pro`、`claude-opus-4-6` 三个主模型，并在末尾保留了一条 `*` fallback 路由。因此 `/models` 会返回显式模型加上一条通配兜底路由。默认会看到类似下面的结果：
+
+```json
+{
+  "data": [
+    {"id": "gpt-5.4", "object": "model"},
+    {"id": "gemini-3.1-pro", "object": "model"},
+    {"id": "claude-opus-4-6", "object": "model"},
+    {"id": "*", "object": "model"}
+  ],
+  "object": "list"
+}
+```
+
+如果你想获取 NewAPI 实际可用的模型名，请直接调用上游：
+
+```powershell
+curl "$env:NEWAPI_API_BASE/models" `
+  -H "Authorization: Bearer $env:NEWAPI_KEY"
+```
+
+说明：
+
+- 不要在当前配置下使用 `only_model_access_groups=true`，因为默认没有配置 model access groups，请求结果会是空数组。
+- 如果客户端直接传 `model=qwen-plus` 之类的名称，前提是该名称必须真实存在于 NewAPI 的 `/models` 返回结果中。
+- 显式注册之外的模型不会自动展开进 `/models` 列表；它们会通过 `*` fallback 透传到 NewAPI。
+
 ## 配置说明
 
-当前 `qwen.yaml` 的关键点：
+当前 `litellm.local.yaml` 的关键点：
 
-- `qwen-chat`：主模型，默认走百炼 `qwen-plus`。
-- `qwen-chat-fallback`：降级模型，默认走百炼 `qwen-flash`。
-- `rpm`：在部署层做第一道限流保护，避免上游配额被瞬时打爆。
-- `num_retries` + `timeout`：对临时失败、超时和抖动做统一收敛。
-- `fallbacks` + `cooldown_time`：主模型异常时自动切到降级模型，并对异常部署做短暂冷却。
+- `model_list`：显式注册 `gpt-5.4`、`gemini-3.1-pro`、`claude-opus-4-6` 三个主模型，并追加 `*` 作为最后兜底。
+- 显式模型优先：常用模型可以稳定出现在 `/models` 里，也方便客户端按固定名称接入。
+- `*` fallback：对 NewAPI 已存在但未显式注册的模型保留透传能力，减少频繁改本地配置的成本。
+- `litellm_params.model`：显式模型映射到 `openai/<模型名>`，fallback 映射到 `openai/*`，继续通过 NewAPI 的 OpenAI 兼容接口转发请求。
+- `master_key`：开启 LiteLLM 网关鉴权，避免任何能访问端口的客户端都直接调用上游。

ai/gateway/litellm/newapi.yaml

@@ -1,15 +1,39 @@
 model_list:
-  # 万能透传：客户端传什么模型名，就转发什么到 NewAPI
+  # 显式注册 OpenAI 系列模型，确保 `/models` 能直接返回可用模型名。
+  - model_name: "gpt-5.4"
+    litellm_params:
+      # `model_name` 保持与上游模型 id 一致，便于客户端直接按 `/models` 结果发起调用。
+      model: "openai/gpt-5.4"
+      api_base: "os.environ/NEWAPI_API_BASE"  # 从环境变量读 NewAPI 地址
+      api_key: "os.environ/NEWAPI_KEY"        # 从环境变量读密钥
+  # 显式注册 Gemini 系列模型，避免 wildcard 路由只返回 `*`。
+  - model_name: "gemini-3.1-pro"
+    litellm_params:
+      # 继续走 OpenAI 兼容入口，由 NewAPI 负责实际模型分发。
+      model: "openai/gemini-3.1-pro"
+      api_base: "os.environ/NEWAPI_API_BASE"  # 从环境变量读 NewAPI 地址
+      api_key: "os.environ/NEWAPI_KEY"        # 从环境变量读密钥
+  # 显式注册 Claude 系列模型，便于 LiteLLM 直接暴露固定模型列表。
+  - model_name: "claude-opus-4-6"
+    litellm_params:
+      # 使用上游真实模型 id，避免代理别名与 NewAPI 模型名脱节。
+      model: "openai/claude-opus-4-6"
+      api_base: "os.environ/NEWAPI_API_BASE"  # 从环境变量读 NewAPI 地址
+      api_key: "os.environ/NEWAPI_KEY"        # 从环境变量读密钥
+  # 把 wildcard 路由放在最后，优先命中显式模型，其余上游模型再走透传兜底。
   - model_name: "*"
     litellm_params:
-      model: "openai/{{ model }}"  # 透传模型名
+      # 对列表外但 NewAPI 已存在的模型保留透传能力，例如 `gpt-5.4-mini`。
+      model: "openai/*"
       api_base: "os.environ/NEWAPI_API_BASE"  # 从环境变量读 NewAPI 地址
       api_key: "os.environ/NEWAPI_KEY"        # 从环境变量读密钥
 # database_url: "sqlite:///./litellm.db"
 # 可选：LiteLLM 网关鉴权（防止滥用）
 general_settings:
   master_key: "os.environ/LITELLM_MASTER_KEY"
   # disable_frontend: true  # 关闭前端页面（纯API模式）
-  proxy_batch_write_at: 60 # 每60秒写入一次数据库
-  database_connection_pool_limit: 10 # 每个 Worker 进程的数据库连接池上限
-  # database_url: "postgresql://admin:12345678@localhost:5432/litellm"
+  # proxy_batch_write_at: 60 # 每60秒写入一次数据库
+  # database_connection_pool_limit: 10 # 每个 Worker 进程的数据库连接池上限
+  # virtual key
+  # litellm_key_header_name: "X-Litellm-Key"
+  # database_url: "postgresql://admin:12345678@in:5432/litellm"