mirror of
https://gitcode.com/JianFeeeee/ModelRouter.git
synced 2026-09-21 01:17:59 +00:00
docs: document LuaJIT build tag, AUTO routing, WebUI, multimodal & disable_thinking
This commit is contained in:
root
55
README.md
55
README.md
@ -4,10 +4,10 @@
|
||||
|
||||
## 实现
|
||||
|
||||
统一 OpenAI 兼容网关：把多个上游 LLM 源（DeepSeek、OpenAI、Anthropic、Gemini、
|
||||
统一 OpenAI 兼容网关：把多个上游 LLM 源（DeepSeek、Qijiar、OpenAI、Anthropic、Gemini、
|
||||
Groq、Mistral、Ollama、KimiCode…）通过 **Lua 适配器** 做协议转换，对内网暴露
|
||||
一个标准 `OpenAI Chat Completions` 接口（`/v1/chat/completions` + `/v1/models`），
|
||||
支持单次结算与 SSE 流式。
|
||||
支持单次结算、SSE 流式、**AUTO 模型路由**与**多模态**透传。
|
||||
|
||||
从 [HomeAgent](https://gitcode.com/JianFeeeee/HomeAgent) 的多源 LLM 适配层
|
||||
（`internal/agent/api/provider.go` + `internal/lua/adapters/*`）抽离而来并独立演进。
|
||||
@ -15,12 +15,17 @@ Groq、Mistral、Ollama、KimiCode…）通过 **Lua 适配器** 做协议转换
|
||||
## 特性
|
||||
|
||||
- **多源**：一个进程内配置任意多个上游源，按请求的 `model` 自动路由。
|
||||
- **AUTO 模式**：`default_model: AUTO` 时按各源模型的 `priority` 自动选最高可用源。
|
||||
- **统一输出**：所有源对外都是 OpenAI 格式（含 `reasoning_content`、`tool_calls`、`usage`）。
|
||||
- **多模态**：`content` 数组（`image_url` 等）在多源间无损透传，Anthropic/Gemini/Ollama 自动转换。
|
||||
- **LuaJIT VM**：基于 golua 绑定的 LuaJIT，每个适配器独立 VM + worker 池，安全并发。
|
||||
- **disable_thinking**：请求 `disable_thinking:true`（或上游对应字段）动态开关推理。
|
||||
- **Lua 适配协议**：每个源挂一个 `.lua` 适配器，完成 `transform_request` /
|
||||
`transform_response` / `transform_stream_chunk` 双向转换，协议差异全在 Lua 层。
|
||||
- **签名 / 请求头钩子**：适配器可定义 `build_headers(meta)`，在 Go 发 HTTP 前
|
||||
动态注入/签名请求头——用于云端 API 校验调用方 app（如 KimiCode 只放行特定
|
||||
agent）。提供 `hmac_sha256_hex` / `sha256_hex` / `base64_encode` 等签名辅助。
|
||||
- **WebUI**：内置管理界面，可在线查看/新增/编辑上游源与模型，写入运行时文件持久化。
|
||||
- **鉴权**：网关自身用 `gateway_keys` 校验客户端 Bearer key；与上游各自的 key 相互独立。
|
||||
- **流式**：SSE `chat.completion.chunk`，含角色首包与 `[DONE]` 收尾。
|
||||
|
||||
@ -28,10 +33,13 @@ Groq、Mistral、Ollama、KimiCode…）通过 **Lua 适配器** 做协议转换
|
||||
|
||||
```bash
|
||||
cp config.example.yaml config.yaml # 编辑你的源与 key
|
||||
GOMODCACHE=... GOPROXY=off go build -o llmsproxy ./cmd/llmsproxy
|
||||
GOMODCACHE=... GOPROXY=off go build -tags luajit -o llmsproxy ./cmd/llmsproxy
|
||||
./llmsproxy -config config.yaml
|
||||
```
|
||||
|
||||
> 依赖 [golua](https://github.com/aarzilli/golua)（LuaJIT 绑定）。**必须**带 `-tags luajit`
|
||||
> 构建，否则默认走内置超集 gopher-lua 路径（行为略有差异）。
|
||||
|
||||
```bash
|
||||
# 无 key -> 401
|
||||
curl http://127.0.0.1:8080/v1/models
|
||||
@ -56,15 +64,23 @@ curl -N -H "Authorization: Bearer sk-gw-local-0001" \
|
||||
```yaml
|
||||
listen: 127.0.0.1:8080 # 网关监听地址（建议绑内网/回环）
|
||||
gateway_keys: [sk-gw-0001] # 客户端访问网关的 key；留空=不鉴权
|
||||
default_source: deepseek # model 无法路由时回落的源
|
||||
default_model: AUTO # model 无法路由时自动按 priority 选源
|
||||
adapter_dir: adapters # Lua 适配目录，首启自动写入内置适配器
|
||||
runtime_file: runtime.json # WebUI 编辑的源持久化到此文件
|
||||
|
||||
sources:
|
||||
- name: deepseek
|
||||
base_url: https://api.deepseek.com
|
||||
api_key: sk-...
|
||||
model: deepseek-v4-flash
|
||||
adapter: deepseek
|
||||
max_concurrent: 8
|
||||
models:
|
||||
- id: deepseek-v4-flash
|
||||
priority: 100 # 越大越优先被 AUTO 选中
|
||||
kind: chat
|
||||
- id: deepseek-v4-pro
|
||||
priority: 60
|
||||
kind: chat
|
||||
# 静态请求头（比适配器默认优先）
|
||||
headers: { X-Tenant: prod }
|
||||
# 传给 Lua build_headers 的透传元数据
|
||||
@ -80,9 +96,21 @@ sources:
|
||||
|
||||
1. `source/model` 或 `source:model` 前缀 → 指定源；
|
||||
2. 精确匹配某个源的 `model`；
|
||||
3. 回落到 `default_source`。
|
||||
3. 配置 `default_model: AUTO` 时 → 按各源模型的 `priority`（数字大优先）选最高可用源；
|
||||
4. 否则回落到 `default_source`。
|
||||
|
||||
任何 OpenAI 客户端，只要 `model` 设为某个源的 `name/任意名`，即可锁定走该源。
|
||||
任何 OpenAI 客户端，只要 `model` 设为某个源的 `name/任意名`，即可锁定走该源；
|
||||
设为 `AUTO`（或网关配了 `default_model: AUTO`）即自动按优先级选源。
|
||||
|
||||
### disable_thinking
|
||||
|
||||
请求体带 `"disable_thinking": true` 时，网关透传给各适配器；DeepSeek 适配器将其
|
||||
映射为 `extra_body.thinking.type = "disabled"` 关闭推理，其余源按各自协议处理。
|
||||
|
||||
### WebUI
|
||||
|
||||
内置管理界面（`GET /`），登录后可在浏览器查看/新增/编辑上游源与模型，
|
||||
改动写入 `runtime_file`（重启仍生效）。
|
||||
|
||||
## Lua 适配器协议
|
||||
|
||||
@ -119,6 +147,10 @@ return {
|
||||
|
||||
`openai` `deepseek` `anthropic` `gemini` `github` `groq` `mistral` `ollama` `kimicode`。
|
||||
|
||||
`anthropic`/`gemini`/`ollama` 适配器内置多模态转换（`image_url` → 各自上游格式）；若
|
||||
源启用 `disable_thinking`，`deepseek` 适配器会把 `extra_body.thinking.type` 置为
|
||||
`disabled`。
|
||||
|
||||
**kimicode** 是展示 `build_headers` 的样例：云端校验调用方 app，需要按
|
||||
`meta.app_secret` 对时间戳+URL+请求体哈希做 HMAC 签名并附 `X-App-Sign` 等头。
|
||||
配好 `sources[].meta.{app_id, app_secret, app_agent}` 即可。
|
||||
@ -128,16 +160,17 @@ return {
|
||||
```
|
||||
cmd/llmsproxy # 入口
|
||||
internal/config # YAML 配置加载/校验
|
||||
internal/lua # Lua VM + AdapterCache + 内置适配器 (embed)
|
||||
internal/lua # LuaJIT VM + worker 池 + AdapterCache + 内置适配器 (embed)
|
||||
internal/provider # Provider(HTTP) + Registry(路由)
|
||||
internal/gateway # OpenAI 兼容 HTTP 服务 + 鉴权 + SDK/流式
|
||||
internal/gateway # OpenAI 兼容 HTTP 服务 + 鉴权 + SDK/流式 + WebUI
|
||||
internal/types # 统一格式 & OpenAI wire 类型
|
||||
```
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
go test -tags luajit ./...
|
||||
```
|
||||
|
||||
覆盖：配置校验、适配器加载/变换、签名钩子、Gateway 鉴权、SDK 结算、SSE 流式、模型路由。
|
||||
覆盖：配置校验、适配器加载/变换、签名钩子、Gateway 鉴权、SDK 结算、SSE 流式、
|
||||
模型路由、多模态透传与 disable_thinking。
|
||||
Reference in New Issue
Block a user