Higress 之五 · 新增接口场景全解（何时改 LiteLLM / 何时改 Higress）

环境：192.168.110.207
系列：之一～四（安装与路由）→ 之五（场景决策）→ 之六（企业级能力展示）
HTML：docs/html_cursor/Higress_之五_新增接口场景全解_cursor.html
本文目的：把「新增一个 API / 模型 / 服务时，到底改谁」说清楚，并给可照做的案例。

0. 内部凭据一览

用途	完整值
Higress Console	`http://192.168.110.207:8001`；`admin` / `Higress207admin!`
Higress 总入口	`http://192.168.110.207:18080`
LiteLLM	`http://192.168.110.207:4000`；Bearer `sk-litellm-bocheng-207`
经 Higress 调模型	`http://192.168.110.207:18080/llm/v1`；Bearer `sk-litellm-bocheng-207`
Xinference	Bearer `xf-K8H3LiS27H4188XdOyWJj74MWMOlIR9tZbiybDbxbSas7eAI`
经 Higress 调向量	`http://192.168.110.207:18080/xf/v1`；Bearer `xf-K8H3LiS27H4188XdOyWJj74MWMOlIR9tZbiybDbxbSas7eAI`
vLLM 上游	Bearer `123456`
Dify	`38205036@qq.com` / `Difyai123456`

更多见之一 §0、patches_cursor/Higress部署/console.env。

1. 先记住两层分工（决策前提）

text

客户端
  │
  ├─ 直连 LiteLLM :4000          ← 只关心「哪个 model」
  │
  └─ 经 Higress :18080
        ├─ /llm/*  → LiteLLM     ← 路径已存在，新模型通常不用改 Higress
        ├─ /xf/*   → Xinference  ← 路径已存在
        └─ /新前缀 → 新服务      ← 才需要新 Higress 路由

组件	回答的问题
LiteLLM	请求里的 `"model":"xxx"` 转发到哪台上游？上游 Key 是什么？要不要多机 LB？
Higress	这个 URL 路径/域名进哪扇门？要不要限流、TLS、统一入口？

一句话：

新的是 模型名 → 多半只动 LiteLLM。
新的是 URL 路径 / 新后端进程 → 多半只动 Higress（或两边都动，见场景 F）。

2. 决策流程图（先看这张再翻案例）

text

你要新增的是什么？
        │
        ├─ A. 只是 LiteLLM 里多一个 model 名（同一上游或新上游）
        │         → 只改 LiteLLM config.yaml
        │         → Higress /llm 不用改
        │
        ├─ B. 客户端改走 Higress，但模型已在 LiteLLM 里
        │         → 两边都不用改配置
        │         → 只改客户端 base_url
        │
        ├─ C. 直连 Xinference 新能力，但仍用现有 /xf 前缀
        │         → 在 Xinference launch 模型；Higress 不用改
        │         → 若希望统一走 /llm 的 embeddings，则加 LiteLLM 条目（场景 A 变体）
        │
        ├─ D. 全新业务 HTTP API（与模型无关，如 /status、/ocr）
        │         → 只改 Higress（服务源 + 路由）
        │         → 不动 LiteLLM
        │
        ├─ E. Dify 网页
        │         → 日常用 :80，一般不改 Higress
        │         → 可选 Host 路由（已有 dify.ai.local）
        │
        └─ F. 新模型 + 还想单独开一个 Higress 路径（如 /llm2）
                  → LiteLLM 与 Higress 都要配

3. 场景对照总表

场景	改 LiteLLM？	改 Higress？	改客户端？	典型例子
A 新 model 别名 / 新上游模型	✅	❌	可选（换 model 名）	`demo-chat`、再挂一台 vLLM
B 已有模型，改走 `:18080/llm`	❌	❌	✅ base_url	SDK 从 `:4000/v1` 换成 `/llm/v1`
C 只用现有 `/xf` 调已有/新 launch 的 embedding	❌（或仅当要挂进 LiteLLM）	❌	换 model 名	Xinference 再 launch 一个 embedding
D 新业务 API	❌	✅	✅ 新 URL	自建 FastAPI `:8777` → `/ops/`
E Dify Web	❌	一般 ❌	浏览器仍 `:80`	办公访问控制台
F 新模型 + 新路径前缀	✅	✅	✅	`/secure-llm/` 单独限流
G 同名多机 LB	✅（同名多条）	❌	❌	已有 `demo-lb`
H 钉死某一台	✅（唯一别名）	❌	换 model 名	`demo-lb-a`
I Dify 里模型供应商改指 Higress	❌	❌	✅（Dify 控制台 API Base）	之四补丁

4. 案例详解

场景 A：只新增一个模型接口（最常见）——只改 LiteLLM

诉求： 对外多一个可调的 chat 名，例如 study-qwen，仍打 183 的 vLLM。

要改：

编辑 patches_cursor/LiteLLM部署/config.yaml，在 model_list 增加：

yaml

  - model_name: study-qwen
    litellm_params:
      model: openai/qwen3.6-27b
      api_base: http://116.62.10.183:8000/v1
      api_key: "123456"
      timeout: 300
      extra_body:
        chat_template_kwargs:
          enable_thinking: false

同步到 /opt/litellm/config.yaml 并 systemctl restart litellm（或跑 LiteLLM_01_部署.py）。

不要改： Higress。/llm/* 已转发到 :4000，新 model 自动可用。

验证（直连与经 Higress 各一次）：

bash

# 直连 LiteLLM
curl -sS http://192.168.110.207:4000/v1/models \
  -H "Authorization: Bearer sk-litellm-bocheng-207" | grep study-qwen

# 经 Higress（配置未改 Higress）
curl -sS http://192.168.110.207:18080/llm/v1/chat/completions \
  -H "Authorization: Bearer sk-litellm-bocheng-207" \
  -H "Content-Type: application/json" \
  -d '{"model":"study-qwen","messages":[{"role":"user","content":"你好"}],"max_tokens":32}'

结论： 这类「OpenAI 兼容模型接口」= 只配 LiteLLM。

场景 B：模型已有，只是客户端改走 Higress——两边配置都不用动

诉求： 原来 base_url=http://192.168.110.207:4000/v1，改成统一入口。

要改： 仅客户端 / Dify 供应商 / 脚本里的 URL。

python

from openai import OpenAI
client = OpenAI(
    api_key="sk-litellm-bocheng-207",
    base_url="http://192.168.110.207:18080/llm/v1",  # 唯一变化
)

不要改： LiteLLM config.yaml、Higress 路由（前提是之三已配好 /llm）。

场景 C：向量仍走 `/xf`，Xinference 里新 launch 了模型

诉求： Xinference 上新起了一个 embedding，uid 叫 bge-small，希望：

bash

curl -sS http://192.168.110.207:18080/xf/v1/embeddings \
  -H "Authorization: Bearer xf-K8H3LiS27H4188XdOyWJj74MWMOlIR9tZbiybDbxbSas7eAI" \
  -H "Content-Type: application/json" \
  -d '{"model":"bge-small","input":"测试"}'

要改：

Xinference 管理端 launch（管理员 admin / admin1234）。
Higress 不用改（/xf 已指向 :9997）。
若还希望 经 LiteLLM 用 "model":"bge-small" 调 embeddings，再在 LiteLLM 加一条（变成场景 A 的 embedding 版）；否则只走 /xf 即可。

场景 D：新增与模型无关的业务 API——只改 Higress

诉求： 207 上有自建服务 http://192.168.110.207:8777/health（示例），希望对外：

http://192.168.110.207:18080/ops/health

要改（Higress Console 或 API）：

服务源 static：name=opsapi，domain=192.168.110.207:8777，port=8777。
路由：前缀 /ops/ → opsapi.static:8777，rewrite 去前缀到 /。

示例（登录后，Cookie 略）：

bash

# 服务源
curl -sS -b /tmp/hc.ck -X POST http://127.0.0.1:8001/v1/service-sources \
  -H "Content-Type: application/json" \
  -d '{
    "name":"opsapi",
    "type":"static",
    "domain":"192.168.110.207:8777",
    "port":8777,
    "protocol":"HTTP",
    "authN":{"enabled":false}
  }'

# 路由
curl -sS -b /tmp/hc.ck -X POST http://127.0.0.1:8001/v1/routes \
  -H "Content-Type: application/json" \
  -d '{
    "name":"ops",
    "domains":[],
    "path":{"matchType":"PRE","matchValue":"/ops/","caseSensitive":false},
    "services":[{"name":"opsapi.static","port":8777,"weight":100}],
    "rewrite":{"enabled":true,"path":"/"},
    "authConfig":{"enabled":false}
  }'

不要改： LiteLLM。这条链路与 model 无关。

验证：

bash

curl -sS http://192.168.110.207:18080/ops/health
# 应等于直连 http://192.168.110.207:8777/health

场景 E：Dify 网页——通常不经过「当 API 网关用」的 Higress

诉求： 打开控制台配 Agent。

推荐： http://192.168.110.207/（:80）。

可选： hosts 配好后用 http://dify.ai.local:18080/（之三已配 Host 路由）。这不是「新增 API」，也不要为此去改 LiteLLM。

场景 F：新模型 + 还要单独 Higress 路径（两边都要配）

诉求： 有个 finance-qwen 模型，且希望：

普通流量：/llm → 现有模型
财务专用：/finance-llm/ → 同一 LiteLLM，但以后单独挂限流插件

步骤 1 — LiteLLM（必须）：

yaml

  - model_name: finance-qwen
    litellm_params:
      model: openai/qwen3.6-27b
      api_base: http://116.62.10.183:8000/v1
      api_key: "123456"

重启 litellm。

步骤 2 — Higress（必须，因为新前缀）：

可复用已有服务源 litellm（192.168.110.207:4000）。
新建路由：/finance-llm/ → litellm.static:4000，rewrite 去前缀。

步骤 3 — 客户端：

text

base_url = http://192.168.110.207:18080/finance-llm/v1
model    = finance-qwen
api_key  = sk-litellm-bocheng-207

结论： 「新路径」触发 Higress；「新 model 名」触发 LiteLLM → 两者都配。

若财务与普通共用 /llm，只靠 model=finance-qwen 区分 → 只需场景 A，不要场景 F。

场景 G / H：负载均衡与钉机——只改 LiteLLM

已在 LiteLLM 文档与 demo-lb / demo-lb-a / demo-lb-b 演示：

同名多条 → LB（G）
唯一别名 → 钉机（H）

Higress 侧始终是 /llm → :4000，不用为 LB 加路由。

bash

# 经 Higress 走均衡名（Higress 无感知有几台上游）
curl -sS http://192.168.110.207:18080/llm/v1/chat/completions \
  -H "Authorization: Bearer sk-litellm-bocheng-207" \
  -H "Content-Type: application/json" \
  -d '{"model":"demo-lb","messages":[{"role":"user","content":"hi"}],"max_tokens":16}'

（当前 demo-lb 上游为模拟端口，失败属预期；看的是「只改 LiteLLM」这一形态。）

场景 I：Dify 模型调用改指 Higress——只改 Dify 配置

诉求： Agent 调模型时也经 :18080。

要改： Dify 控制台 → 模型供应商 → API Base = http://192.168.110.207:18080/llm/v1（或容器内探测通的地址），API Key = sk-litellm-bocheng-207。

不要改： LiteLLM / Higress 路由（之三已通时）。详细探测见之四与 Higress_04_探测Dify容器访问Higress.sh。

5. 易混点 FAQ

Q1：新增 API 是不是两者都要配？ A：不是。先问是「新 model」还是「新 URL/新进程」。见 §2、§3。

Q2：经 Higress 调模型，是否还要在 Higress 里填一遍上游 Key？ A：否。Higress 一期透传 Authorization；上游 Key 在 LiteLLM 的 api_key 或 Xinference 的 Bearer。

Q3：只开了 LiteLLM，不配 Higress，能不能调模型？ A：能。:4000 直连即可。Higress 是可选前门。

Q4：只配了 Higress /llm，LiteLLM 没加 model，行不行？ A：请求能到 LiteLLM，但会报模型不存在。路径通 ≠ 模型已注册。

Q5：/xf 和 LiteLLM 里的 bge-m3 啥关系？ A：两条路都能做向量：

/xf → 直打 Xinference；
/llm + model=bge-m3 → LiteLLM 再转 Xinference。

新 embedding 可只走其中一条。

6. 推荐习惯（本环境）

角色	习惯
日常加模型	只改 LiteLLM + 重启；用 `:4000` 或 `:18080/llm` 验收
日常 Dify 网页	`:80`
对外只暴露一端口、或要网关限流	客户端走 Higress；限流挂在 Higress 路由上
新业务 HTTP	只配 Higress 新前缀

7. 系列导航

之一 · 理论与架构
之二 · Compose 安装与控制台
之三 · 总入口路由与验收
之四 · 增强与附录
本文 · 新增接口场景全解
之六 · 企业级能力展示（证书/限流/WAF/SSE/缓存等）

附录 A：场景速查卡片（可打印）

text

【只改 LiteLLM】新 model / LB / 钉机别名
【只改 Higress】新业务 URL 前缀、新 Host、网关限流挂载
【两边都改】新 model 且新开专用路径前缀（少见，按需）
【只改客户端】base_url 在 :4000 与 :18080/llm 之间切换；Dify API Base
【几乎不改网关】Dify 网页继续 :80

附录 B：场景 A 最小操作清单（复制）

bash

# 1) 改 patches_cursor/LiteLLM部署/config.yaml 增加 model_name
# 2) 部署
python scripts_cursor/LiteLLM部署/LiteLLM_01_部署.py
# 3) 验收
curl -sS http://192.168.110.207:18080/llm/v1/models \
  -H "Authorization: Bearer sk-litellm-bocheng-207"

附录 C：场景 D 最小操作清单（复制）

bash

# 1) Console 登录
curl -sS -c /tmp/hc.ck -X POST http://127.0.0.1:8001/session/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Higress207admin!"}'
# 2) 按 §4 场景 D 创建 service-source + route
# 3) curl 总入口新前缀对比直连端口

附录 D：`console.env` 中与本册相关的键（完整文件见之二）

env

CONSOLE_URL=http://192.168.110.207:8001
ADMIN_USER=admin
ADMIN_PASS=Higress207admin!
LITELLM_MASTER_KEY=sk-litellm-bocheng-207
LITELLM_VIA_HIGRESS=http://192.168.110.207:18080/llm/v1
XF_KEY=xf-K8H3LiS27H4188XdOyWJj74MWMOlIR9tZbiybDbxbSas7eAI
XF_VIA_HIGRESS=http://192.168.110.207:18080/xf/v1
VLLM_KEY=123456
DIFY_EMAIL=38205036@qq.com
DIFY_PASSWORD=Difyai123456

Higress 之五 · 新增接口场景全解

Higress 之五 · 新增接口场景全解（何时改 LiteLLM / 何时改 Higress）

0. 内部凭据一览

1. 先记住两层分工（决策前提）

2. 决策流程图（先看这张再翻案例）

3. 场景对照总表

4. 案例详解

场景 A：只新增一个模型接口（最常见）——只改 LiteLLM

场景 B：模型已有，只是客户端改走 Higress——两边配置都不用动

场景 C：向量仍走 /xf，Xinference 里新 launch 了模型

场景 D：新增与模型无关的业务 API——只改 Higress

场景 E：Dify 网页——通常不经过「当 API 网关用」的 Higress

场景 F：新模型 + 还要单独 Higress 路径（两边都要配）

场景 G / H：负载均衡与钉机——只改 LiteLLM

场景 I：Dify 模型调用改指 Higress——只改 Dify 配置

5. 易混点 FAQ

6. 推荐习惯（本环境）

7. 系列导航

附录 A：场景速查卡片（可打印）

附录 B：场景 A 最小操作清单（复制）

附录 C：场景 D 最小操作清单（复制）

附录 D：console.env 中与本册相关的键（完整文件见之二）

场景 C：向量仍走 `/xf`，Xinference 里新 launch 了模型

附录 D：`console.env` 中与本册相关的键（完整文件见之二）