unis-oa/docs/llm-integration.md

18 KiB
Raw Permalink Blame History

大模型接入(服务商配置)

本文是「大模型接入」这个功能的配置文档:入口在哪、支持哪些服务商与报文协议、 一条接入里每个字段管什么、密钥怎么进怎么出、测试连通 与 试运行 分别做什么、 出问题先看哪里。

代码侧的分工: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 统一能力层)。