18 KiB
大模型接入(服务商配置)
本文是「大模型接入」这个功能的配置文档:入口在哪、支持哪些服务商与报文协议、
一条接入里每个字段管什么、密钥怎么进怎么出、测试连通 与 试运行 分别做什么、
出问题先看哪里。
代码侧的分工:app/llmconfig.py 管目录与协议(谁是哪家、地址怎么拼、鉴权头怎么带),
app/service/llm.py 管收发与解读(五种报文、错误翻成中文、失败补试),
app/api/ai.py 管校验、落库、审计。界面在 frontend/src/views/oa/AiProviderView.vue。
本文只管接入。接进来之后在系统里怎么用 —— 助手页面长什么样、哪些页面该有入口、 外发内容的口径、审计与分期 —— 是另一份文档:大模型怎么用。
1. 一个入口,两件东西
系统管理 → 大模型接入(/settings/ai-models,权限 system:setting)。这一页同时管两类东西:
| 东西 | 存在哪 | 改完什么时候生效 |
|---|---|---|
| 接入配置(服务商、接口地址、密钥、模型清单、采样参数、启停、默认接入) | MySQL 表 oa_ai_provider,一家一条 |
保存即生效:每次调用现读这一行,不用重启后端 |
| 大模型能力(总闸、补试次数、日志口径) | oa_system_setting 的 config:ai 行(见 §6) |
保存即生效 |
页头那张「能力总闸」卡片管的是第二件,系统设置页里同名的「大模型能力」配置组是同一份数据。
一句话边界:ai_enabled 决定业务功能能不能真的去调模型;接入本身什么时候都能配、
能测、能试运行 —— 先把接入验通,再打开总闸,是这个页面刻意留出来的顺序。
2. 支持什么:5 种报文协议 × 24 家服务商预设
「报文协议」决定请求长什么样、正文在响应的哪一段、鉴权头怎么带。目录里没有的厂商
选 自定义 / 其他网关,先挑协议再填地址与密钥,一样能接。
| 协议 | 鉴权 | 对话接口 | 列模型 | 接口地址要填到哪一层 |
|---|---|---|---|---|
openai OpenAI 兼容(Chat Completions) |
Authorization: Bearer <密钥> |
{前缀}/chat/completions |
{前缀}/models |
填到 /v1(或网关自定义那一段) |
azure_openai Azure OpenAI |
api-key: <密钥> |
{前缀}/chat/completions?api-version=… |
不支持(Azure 的部署名不等于模型名) | 填到部署名:https://资源名.openai.azure.com/openai/deployments/部署名 |
anthropic Anthropic Messages |
x-api-key: <密钥> + anthropic-version |
{站点}/v1/messages |
{站点}/v1/models |
填站点根:https://api.anthropic.com |
gemini Google Gemini |
x-goog-api-key: <密钥> |
{站点}/v1beta/models/{模型}:generateContent |
{站点}/v1beta/models |
填站点根 |
ollama Ollama |
不鉴权 | {站点}/api/chat |
{站点}/api/tags |
填站点根:http://127.0.0.1:11434 |
装了 Ollama 想统一口径,也可以选 openai 协议把地址写成 http://127.0.0.1:11434/v1。
下面是界面上的服务商下拉(GET /api/v1/ai/catalog 的返回,不写死在前端)。选一家就
带出厂接口地址、密钥栏的叫法、常用模型清单和一句话提醒;预设只是填表的草稿纸,
带出来的东西全都能改。
国内厂商(都是 OpenAI 兼容)
| 服务商 | 目录键 | 出厂接口地址 |
|---|---|---|
| 阿里云百炼(通义千问) | dashscope |
https://dashscope.aliyuncs.com/compatible-mode/v1 |
| DeepSeek 深度求索 | deepseek |
https://api.deepseek.com/v1 |
| 智谱 GLM | zhipu |
https://open.bigmodel.cn/api/paas/v4 |
| Kimi(月之暗面) | moonshot |
https://api.moonshot.cn/v1 |
| 火山方舟(豆包) | doubao |
https://ark.cn-beijing.volces.com/api/v3 |
| 腾讯云混元 | hunyuan |
https://api.hunyuan.cloud.tencent.com/v1 |
| 讯飞星火 | spark |
https://spark-api-open.xf-yun.com/v1 |
| 百川智能 | baichuan |
https://api.baichuan-ai.com/v1 |
| 零一万物 Yi | yi |
https://api.lingyiwanwu.com/v1 |
| 阶跃星辰 Step | stepfun |
https://api.stepfun.com/v1 |
| 硅基流动 SiliconFlow | siliconflow |
https://api.siliconflow.cn/v1 |
| MiniMax | minimax |
https://api.minimaxi.com/v1 |
海外厂商
| 服务商 | 目录键 | 协议 | 出厂接口地址 |
|---|---|---|---|
| OpenAI | openai |
openai |
https://api.openai.com/v1 |
| Anthropic Claude | anthropic |
anthropic |
https://api.anthropic.com |
| Google Gemini | gemini |
gemini |
https://generativelanguage.googleapis.com |
| Azure OpenAI | azure_openai |
azure_openai |
没有出厂地址,按部署填到部署名 |
| xAI Grok | xai |
openai |
https://api.x.ai/v1 |
| Groq | groq |
openai |
https://api.groq.com/openai/v1 |
本地 / 私有化(都不需要密钥)
| 服务商 | 目录键 | 协议 | 出厂接口地址 |
|---|---|---|---|
| Ollama(本机) | ollama |
ollama |
http://127.0.0.1:11434 |
| vLLM(自建) | vllm |
openai |
http://127.0.0.1:8000/v1 |
| Xinference | xinference |
openai |
http://127.0.0.1:9997/v1 |
| LM Studio | lm_studio |
openai |
http://localhost:1234/v1 |
网关与自定义
| 服务商 | 目录键 | 说明 |
|---|---|---|
| OpenRouter | openrouter |
https://openrouter.ai/api/v1,OpenAI 兼容 |
| 自定义 / 其他网关 | custom |
空白表:先挑协议,再填地址与密钥 |
要加一家:在 app/llmconfig.py 的 PROVIDERS 里加一条 ProviderSpec(出厂地址、密钥
栏叫法、要不要密钥、常用模型、文档链接、一句话提醒)就完了,界面、校验、测试、
试运行都跟着认,不用改前端。
3. 一条接入的字段
| 字段 | 界面上叫什么 | 管什么 |
|---|---|---|
name |
接入名称 | 认人用,全表唯一;界面列表与操作日志都靠它 |
provider |
服务商 | 目录键。换服务商顺带换一套协议与默认值,除非这次明确给了协议 |
protocol |
报文协议 | 见 §2。跟服务商不搭时以这里为准 |
base_url |
接口地址(前缀) | 填到哪一层见 §2 的表。保存时挡三种常见错填:把 chat/completions 整段粘进来、file:// 之类不像 API 的 scheme、地址里带账号密码 |
api_key |
API Key | 只进不出,见 §4 |
api_version |
API 版本 | Azure 必填(2024-10-21 这种),Gemini 可用来换 v1beta;其余协议用不上,界面上只在需要的协议下出现 |
models |
可选模型 | 界面上能选的那几个模型名,一行一个或逗号分隔。可以用「拉取模型清单」从服务商那边抄 |
default_model |
默认模型 | 不带模型名时用它;留空则用清单第一个 |
temperature / max_tokens / timeout_seconds |
温度 / 最大生成长度 / 超时(秒) | 采样与超时。试运行时可以临时改最大生成长度 |
system_prompt |
系统提示词 | 每次调用都带在开头;留空表示不带 |
extra_body / extra_headers |
高级里的两个 JSON | 各家私有参数(top_p、思考开关…)与网关要求的请求头,随请求一起带走 |
enabled |
启用这条接入 | 停用的接入不参与选路,但界面上照样能测、能试运行 |
is_default |
默认接入 | 全表只有一个。勾新的把旧的撤掉;默认那条被停用或删掉时,默认自动顺延给启用列表里的第一条 |
order_number |
排序号 | 列表与「默认接入顺延」都按它排 |
last_test_* |
最近测试 | 「测试连通」写回来的结论、模型、耗时、时间与操作人,只读 |
4. 密钥口径:只进不出
- 接口只回
api_key_set(配了没有)和一句key_hint(还顺带说清这家的鉴权方式)。 列表、详情、测试、试运行、草稿试跑的响应里都没有密钥明文。 - 保存时
api_key留空 = 不改这一项,所以编辑弹窗里那栏的空不是「清空」。想换密钥 直接填新的;要把一条接入彻底清空密钥,目前只能删掉重建(本地推理服务请选 Ollama / vLLM 这类不需要密钥的预设)。 - 该有密钥的一家在新建时不给密钥会被直接挡下(「本地推理服务请选 Ollama/vLLM 这类预设」), 不等到第一次调用才发现。
- 操作日志只写动作和改了哪些字段名,值一律不落:
API Key(值不记录)。 - 服务商回来的错误原文先过一遍
llmconfig.redact(),把密钥摘掉才进日志与界面。 - 数据库里存的是明文,与 MinIO
secret_key、Hub 目录密钥同口径:这台 MySQL 按 「能看到库就能看到一切」的边界对待,密钥的保护靠接口不回显与日志不写值。
5. 四个「试」的口径
| 动作 | 接口 | 做什么 | 失败时 |
|---|---|---|---|
| 测试连通 | POST /ai/providers/{id}/test |
先列模型,再拿清单里的模型发一条很短的对话(正文 ping、max_tokens=16)。以发对话那步为准:有些网关不给列模型接口,列模型失败只写进步骤里不算失败。结论写回 last_test_* |
仍回 200,data.ok=false,data.steps[] 说清哪一步验了什么。只有「连测都没法测」(地址为空、一个模型都拿不到)才 400 |
| 试运行 | POST /ai/providers/{id}/chat |
真发一句话,回正文、用的模型、耗时与 usage;顺带把「最近测试」刷成「试运行成功(Xms)」 |
400(没说提示词、地址不通、上游报错都是 400 AI_UPSTREAM) |
| 拉取模型清单 | GET /ai/providers/{id}/models |
把服务商那边的模型名抄回来 | 400(协议不支持就是 400,界面上按钮也会藏起来) |
| 先试一次(草稿试跑) | POST /ai/test |
拿当前表单还没保存的内容发同样的两步。不写库、不写「最近测试」;带 id 只是为了借用那条已存接入的密钥,响应里也拿不到它 |
同「测试连通」:200 + ok:false + steps[] |
失败补试走配置项 ai_retries(默认 2,见 §6):只补「连不上、超时、对方 5xx、被限流」
这类可能一会的错;参数被拒、密钥不对这种一定失败的直接报错,不浪费时间。
错误一律翻成一句照着能改的中文(后面用 | 拼上服务商给的原因),例如:
密钥不对或没有这个权限(401/403)、
地址或模型找不到(404):OpenAI 兼容协议的接口地址要填到前缀那一段,例如 https://api.openai.com/v1;模型名也要跟服务商给的一致、
被限流了(429):配额用完或请求太快,稍后再试、
对方返回的不是 JSON:接口地址多半填到了控制台或网页那一层、
60 秒内没连上或没回话:可能是地址写错、对方排队太久,或本机到这个地址不通。
服务商原文进后端日志(截断 + 摘密钥),界面上不堆英文。
6. 总闸与调用策略:三个配置项
这一组是系统那套统一配置的一部分(注册在 app/dbconfig.py,界面在系统设置页
「大模型能力」组,大模型接入页的总闸卡片是同一份数据的另一块入口)。取值优先级
环境变量 > 数据库 config:ai > config.toml > 代码默认值,出厂模板见
backend/config.toml.example 的 [ai] 段。
| 配置项 | 环境变量 | 出厂值 | 管什么 |
|---|---|---|---|
ai_enabled |
OA_AI_ENABLED |
false |
业务功能能不能真的去调大模型。关掉不影响列表里的测试连通与试运行 |
ai_retries |
OA_AI_RETRIES |
2 |
失败补试次数,0-5,0 = 不补试。补哪些错见 §5 |
ai_log_prompt |
OA_AI_LOG_PROMPT |
false |
打开后运行日志带上提示词与回复(各截断 400 字)。提示词里可能有内部数据,默认只记长度 |
界面上每一项都写明这个值是谁给的(配置文件 / 数据库 / 环境变量);总闸卡片保存时
用的是同一套约定:没出现的项不动,显式传 null 是把这一项从库里删掉、改回出厂值。
7. 代理与直连(本机模型最常见的「地址明明对却连不上」)
开发机上常见的 clash / v2ray 会设 http_proxy=127.0.0.1:7890,而 Python 的 urllib
不会自动为 127.0.0.1 放行:照着默认走代理,请求就绕去代理软件那儿回了个 502,
看起来像本机模型没起来。
规则(app/service/llm.py 的 _wants_direct() / _opener_for()):
- 目标是
localhost,或 IP 落在回环与内网网段(127.0.0.0/8、::1/128、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、169.254.0.0/16、100.64.0.0/10)—— 忽略http_proxy直连。目录里的 Ollama / vLLM / LM Studio / Xinference 与大多数自建网关 都落在这里。 - 公网地址照环境变量走,
no_proxy照旧管用;连不上时错误里会补一句 「本机设了 http_proxy,必要时把地址写进 no_proxy 试试」。
8. 接口清单
全部要求登录且带 system:setting 权限,写操作记进操作日志(ai_provider_create /
ai_provider_update / ai_provider_delete / ai_chat_test / ai_config_update),
日志与响应都不含密钥。前缀 /api/v1。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /ai/config |
总闸与两个策略项:值、中文说明、谁给的 |
| PUT | /ai/config |
保存这一组;传 null 改回出厂值 |
| GET | /ai/catalog |
服务商与协议目录(下拉、默认地址、密钥叫法、文档链接) |
| GET | /ai/providers |
接入列表。?enabled_only=1 只看启用的 |
| POST | /ai/providers |
新增 |
| PUT | /ai/providers/{id} |
修改。没出现的字段不动,api_key 留空 = 不改 |
| DELETE | /ai/providers/{id} |
删除 |
| GET | /ai/providers/{id}/models |
从服务商拉模型清单 |
| POST | /ai/providers/{id}/test |
测试连通(可带 model / prompt) |
| POST | /ai/providers/{id}/chat |
试运行(model / prompt / max_tokens / temperature) |
| POST | /ai/test |
拿没保存的表单试一次,不写库 |
9. 出问题先看哪里
| 现象 | 大概率原因 | 怎么办 |
|---|---|---|
密钥不对或没有这个权限(401/403) |
密钥串错、复制漏字符、密钥带空格 | 界面上重新粘一次(填了就是覆盖)。Authorization: Bearer 前缀不用自己写,协议会带 |
地址或模型找不到(404) |
地址层级填错:OpenAI 兼容少了 /v1、Anthropic/Gemini 多带了 /v1/messages、Azure 没填到部署名;也可能是模型名写错 |
照 §2 最后那一列重填。「测试连通」的 steps 会指出是列模型那步还是发对话那步 404 |
对方返回的不是 JSON |
地址填到了控制台、网页或反代首页 | 换成真正的 API 前缀 |
Azure 报缺 api-version |
「API 版本」留空 | 填 2024-10-21 这类版本号 |
| 本机 Ollama / vLLM 连不上,但浏览器打得开 | 走了 http_proxy |
看 §7。内网地址现在都直连;自建网关用了公网域名的,把域名写进 no_proxy |
| 一直在等,最后超时 | 本地模型在排队 / 首 token 很慢 | 把这条接入的「超时(秒)」调大;推理类模型(deepseek-reasoner 等)尤其要放宽 |
| 回了空正文 | 有的网关把正文放在别的字段 | 界面上看 steps;确认报文形状后可在「附加参数」里补这家要求的字段 |
| 界面上「拉取模型清单」是灰的 | 这家协议不支持列模型(Azure) | 手填模型名 |
| 配好测通了,业务功能还是不调 | 总闸 ai_enabled 没开 |
页头「能力总闸」打开,或系统设置 →「大模型能力」里改 |
10. 验收脚本与桩服务商
cd backend
python3 tests/ai_providers.py # 112 项断言,自带临时库 unis_oa_aitest 与一台桩服务商
python3 tests/llm_stub.py --port 9150 # 只起桩,手工联调用
桩服务商一个端口演十家,路径即前缀:/echo/v1(Bearer ak-echo)、/claude/v1
(x-api-key ak-claude)、/gemini/v1beta、/native(Ollama)、
/azure/openai/deployments/deploy-1,另有 /badkey、/empty、/html、/slow、
/flaky 几种坏脾气。它会校验报文形状:Anthropic 缺 system/max_tokens/版本头回
400,Ollama 的 stream 不是 false 回 400,Azure 缺 api-version 回 400 —— 所以它
同时也是「我们发出去的报文对不对」的镜子。
脚本还会拿坏代理起后端进程,专门证明 §7 那套直连规则管用。
11. 业务侧怎么调
from app.service import llm
result = llm.generate("把这段审批意见改得正式一点", rows=启用的接入行)
result["text"] # 正文
result["model"] # 实际用的模型
generate() 只看两件事:总闸开着吗(关着抛「大模型能力当前是关闭的」),以及点名要哪
条接入(不点名就用默认接入)。它不碰数据库,rows 由调用方给,免得业务代码被会话
生命周期绑住。
截至目前还没有业务功能调它 —— 接入、测试、试运行、密钥管理这一整套已经可用,
第一条接进来的功能(摘要、辅助填写之类)按上面这一段接即可:读一遍 oa_ai_provider
的启用行交给 generate(),异常原样翻给用户看,因为话已经是照着能改的中文了。
真要做第一条功能时别直接在业务页面里调 generate():开关、权限、上下文脱敏、限流、
缓存、审计这六件事要在一个统一层里做完,方案与落点见
大模型怎么用(§2 统一能力层)。