Skip to content

模型配置 ​

模型配置用于定义 Snail AI 调用模型服务所需的模型标识、端点、密钥和高级参数。本文以当前源码已落地能力为准,避免把兼容接入误写成内置 Provider。

概览 ​

当前源码已落地的调用规格:

能力支持方式典型用途
ChatOpenAI-compatible Chat Completions、OpenAI Responses智能体对话、图片输入识别、reasoning、工具调用后的回答生成
EmbeddingOpenAI-compatible EmbeddingRAG 文档向量化、语义检索
RerankQwen/HTTP Rerank检索结果重排

Claude、Gemini、Ollama、火山引擎等服务如果提供 OpenAI-compatible 接口,可以按兼容端点验证接入;不要把它们理解为当前源码内置的一等 Provider。

配置数据结构 ​

每条模型配置通常包含以下字段:

字段类型必填说明
providerIdnumber是所属提供商 ID
modelNamestring是页面展示名称,如 GPT-4o
modelKeystring是API 调用时使用的模型标识,如 gpt-4o
modelTypestring是当前建议使用 CHAT、EMBEDDING、RERANKER
adapterKeystring否底层协议适配器;为空时按模型类型使用默认适配器
apiKeystring是API 密钥,存储时加密
apiEndpointstring是API 根地址或兼容端点地址
configJsonobject否高级参数,JSON 格式;图片输入能力写入 capabilities
scopestring否作用域,如全局或个人配置
isDefaultboolean否是否为该类型默认模型
isEnabledboolean否是否启用
descriptionstring否模型说明

OpenAI-compatible Chat ​

json
{
  "providerId": 1,
  "modelName": "GPT-4o",
  "modelKey": "gpt-4o",
  "modelType": "CHAT",
  "adapterKey": "openai-compatible",
  "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxx",
  "apiEndpoint": "https://api.openai.com/v1",
  "description": "OpenAI-compatible Chat 模型",
  "configJson": {
    "temperature": 0.7,
    "topP": 1.0,
    "maxTokens": 4096,
    "capabilities": ["vision"]
  }
}

兼容服务示例:

json
{
  "providerId": 1,
  "modelName": "DeepSeek Chat",
  "modelKey": "deepseek-chat",
  "modelType": "CHAT",
  "adapterKey": "openai-compatible",
  "apiKey": "sk-xxxxxxxxxxxx",
  "apiEndpoint": "https://api.deepseek.com",
  "description": "通过 OpenAI-compatible 接口接入"
}

填写兼容端点前,请确认目标服务是否兼容 OpenAI Chat Completions 或当前源码使用的请求格式。

OpenAI Responses Chat ​

选择 openai-responses 适配器后,Snail AI 使用 Spring AI OpenAiResponsesChatModel 调用提供商的 Responses API。该适配器是显式选择项,openai-compatible 仍是 CHAT 默认值。

json
{
  "providerId": 1,
  "modelName": "OpenAI Responses",
  "modelKey": "gpt-5",
  "modelType": "CHAT",
  "adapterKey": "openai-responses",
  "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxx",
  "apiEndpoint": "https://api.openai.com/v1",
  "configJson": {
    "timeoutMs": 300000,
    "maxRetries": 2,
    "temperature": 0.7,
    "topP": 1.0,
    "maxTokens": 8192,
    "responseFormat": "text",
    "reasoningEffort": "medium",
    "reasoningSummary": "auto",
    "verbosity": "medium",
    "toolChoice": "auto",
    "parallelToolCalls": true,
    "maxToolCalls": 8,
    "hostedTools": []
  }
}

Responses 参数契约:

configJson 字段可选值/类型Responses 映射
timeoutMs正整数请求超时,默认 300000 ms
maxRetries非负整数最大重试次数
temperaturenumbertemperature
topPnumbertop_p
maxTokens正整数max_output_tokens
responseFormattext、json_object输出格式
reasoningEffortnone、minimal、low、medium、high、xhigh推理强度
reasoningSummaryauto、concise、detailed推理摘要模式
verbositylow、medium、high回答详细程度
toolChoiceauto、none、required工具选择策略
parallelToolCallsboolean是否允许并行工具调用
maxToolCalls正整数单次 Responses 调用允许的最大工具调用数
hostedToolsobject[]提供商侧 Hosted Tools。本期仅 code_interpreter、image_generation、raw
extraBodyobject提供商扩展请求体

topK、frequencyPenalty、presencePenalty、stopSequences 和 seed 不会发送给 Responses API,管理端在选择 openai-responses 时也会隐藏这些字段。已知枚举值、数值范围或 Hosted Tool 结构错误会在模型创建阶段直接报错。

Responses 调用失败时不会回退到 Chat Completions。这个适配器只扩展内部模型调用链路,不提供 Snail AI 对外的 /v1/responses API。

Hosted Tools ​

hostedTools 是带 type 的结构化数组。Hosted Tool 由模型提供商执行,不经过 Snail AI 的本地 ToolCallback:

type字段约束
code_interpretercontainerId容器 ID 可选
image_generationmodel、size尺寸可选 auto/1024x1024/1536x1024/1024x1536
rawtooltool 必须是包含 type 的对象
json
{
  "hostedTools": [
    {
      "type": "code_interpreter",
      "containerId": "cntr_123"
    },
    {
      "type": "image_generation",
      "model": "gpt-image-1",
      "size": "1024x1024"
    },
    {
      "type": "raw",
      "tool": {
        "type": "provider_extension"
      }
    }
  ]
}

本期不接入厂商 Hosted MCP、Web Search 和 File Search。hostedTools、raw.tool.type 和 extraBody.tools[].type 中出现 mcp、web_search、web_search_preview 或 file_search 时,模型创建阶段直接拒绝。

本地 MCP ​

本地函数、Skill 和 MCP 继续注册为 Spring AI ToolCallback,由 Snail AI 所在网络内执行:

text
OpenAI Responses 返回工具调用
        ↓
Snail AI 执行本地函数 / Skill / MCP ToolCallback
        ↓
Snail AI 将工具结果提交给 Responses 模型
        ↓
模型生成最终回复

厂商 Hosted MCP 不在本期范围,现有 MCP headers、存储和凭据配置保持不变。

图片输入识别 ​

模型配置面板中的“支持图片输入”开关用于声明该 CHAT 模型具备视觉输入能力。开启后,configJson.capabilities 会包含 vision:

模型配置支持图片输入

json
{
  "modelType": "CHAT",
  "adapterKey": "openai-compatible",
  "configJson": {
    "capabilities": ["vision"]
  }
}

开启后,智能体对话预览和对话 API 可以随用户消息携带图片附件。图片会以多模态媒体消息发送给模型客户端,不会把 base64 当作普通文本发送。

使用图片输入需要同时满足:

条件说明
模型类型必须是 CHAT
视觉能力configJson.capabilities 包含 vision
模型服务实际模型和兼容端点需要支持图片输入
图片限制每次对话最多 3 张,支持 JPG、PNG、WEBP,单张不超过 10MB

“作为 OCR 视觉兜底模型”用于 RAG Docling 图片 OCR 兜底场景,对应 configJson.defaultVisionModel=true。普通智能体图片对话只要求开启“支持图片输入”;只有需要在 PaddleOCR 无结果时用视觉模型兜底识别文档图片,才需要设置默认视觉模型。

OpenAI-compatible Embedding ​

json
{
  "providerId": 1,
  "modelName": "Text Embedding 3 Small",
  "modelKey": "text-embedding-3-small",
  "modelType": "EMBEDDING",
  "adapterKey": "openai-compatible",
  "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxx",
  "apiEndpoint": "https://api.openai.com/v1",
  "configJson": {
    "embeddingDimension": 1536,
    "encodingFormat": "float",
    "timeoutMs": 60000,
    "maxRetries": 2
  }
}

Embedding 维度必须与向量库配置一致。例如 PgVector 配置了 dimensions: 1536,就应选择输出 1536 维的 Embedding 模型或调整向量表配置。

Qwen/HTTP Rerank ​

json
{
  "providerId": 2,
  "modelName": "Qwen Rerank",
  "modelKey": "gte-rerank",
  "modelType": "RERANKER",
  "adapterKey": "qwen-rerank",
  "apiKey": "your-api-key",
  "apiEndpoint": "https://dashscope.aliyuncs.com",
  "description": "用于 RAG 检索结果重排",
  "configJson": {
    "rerankPath": "/rerank",
    "timeoutMs": 60000
  }
}

Rerank 模型通常用于 RAG 检索后,对候选分片重新排序,提升最终上下文质量。

模型配置验证 ​

保存模型配置后,可以在管理后台模型列表点击「验证」,或调用管理 API:

bash
curl -X POST 'http://localhost:8900/snail-ai/ai-model/config/{id}/test' \
  -H 'Snail-Ai-Auth: <admin-token>'

验证接口会复用已保存的 apiEndpoint、apiKey、modelKey 和 adapterKey,并按模型类型发起一次最小探活请求:

模型类型探活方式成功条件
CHAT发送一条 Hi 单轮消息能拿到 Chat 响应
EMBEDDING对 test 生成一次向量能拿到向量结果
RERANKER用单 query、单文档执行 top1 重排能拿到重排结果

成功时 data 中返回:

json
{
  "success": true,
  "message": "连接成功",
  "responseTimeMs": 5003
}

失败时接口仍会在 data 中返回诊断结果,例如:

json
{
  "success": false,
  "message": "401 Unauthorized",
  "responseTimeMs": 612
}

验证失败通常说明 API Key、端点、模型标识、协议适配器或网络访问存在问题。配置不存在等业务错误会走全局异常响应。

configJson 高级参数 ​

Chat 参数 ​

参数类型说明
temperaturenumber生成随机性,值越高越随机
topPnumber核采样概率
maxTokensnumber最大输出 Token 数
timeoutMsnumber请求超时时间,单位毫秒
maxRetriesnumber最大重试次数;必须为非负整数
responseFormatstring输出格式;适配器支持范围以对应协议为准
capabilitiesstring[]模型能力标记;包含 vision 时表示支持图片输入
defaultVisionModelboolean是否作为 RAG Docling 图片 OCR 的默认视觉兜底模型
extraBodyobject提供商扩展请求体;不要放置 API Key 等凭据

示例:

json
{
  "temperature": 0.3,
  "topP": 0.9,
  "maxTokens": 8192,
  "timeoutMs": 60000,
  "capabilities": ["vision"],
  "defaultVisionModel": false
}

Embedding 参数 ​

参数类型说明
embeddingDimensionnumber向量维度
encodingFormatstringfloat 或 base64;未知值回退提供商默认值
timeoutMsnumber请求超时时间,单位毫秒
maxRetriesnumber最大重试次数

Rerank 参数 ​

参数类型说明
rerankPathstringRerank 请求路径,默认 /rerank
timeoutMsnumber请求超时时间,单位毫秒

默认模型管理 ​

系统可为常用模型类型配置默认模型。默认模型通常用于:

  • 创建智能体时未显式指定 Chat 模型。
  • 创建知识库时未显式指定 Embedding 模型。
  • RAG 链路需要默认 Rerank 模型时。

同一模型类型建议只保留一个默认模型,避免运行时选择不明确。

启用与禁用 ​

禁用模型后:

  • 不应再出现在新的模型选择列表中。
  • 已绑定该模型的智能体或知识库需要尽快切换配置。
  • 历史调用统计仍可保留用于审计和排查。

删除模型前,建议先禁用并观察一段时间。

API Key 加密 ​

Snail AI 会加密保存模型 API Key。生产环境必须设置并备份:

bash
export SNAIL_AI_CRYPTO_KEY=your_32_char_secret_key
export SNAIL_AI_CRYPTO_IV=your_32_char_initial_vector

注意:

  • 不要在 description 或 configJson 中填写密钥。
  • 不要在已有加密数据后随意更换密钥和 IV。
  • 更换密钥后,历史 API Key 可能无法解密,需要重新录入。

常见问题 ​

apiEndpoint 应该填什么? ​

填写模型服务的根地址或兼容端点地址,不要把具体业务路径和模型名拼进去。实际路径由模型适配代码决定。

adapterKey 应该填什么? ​

通常保持默认即可。当前默认值为:

模型类型默认适配器
CHATopenai-compatible
EMBEDDINGopenai-compatible
RERANKERqwen-rerank

需要使用 OpenAI Responses 时,为 CHAT 模型显式选择 openai-responses。该选择不会改变其他模型配置,也不会修改默认适配器。

modelKey 和 modelName 有什么区别? ​

  • modelKey 是发送给模型服务的真实模型标识。
  • modelName 是在 Snail AI 界面展示的名称。

为什么不直接列出 Claude、Gemini、Ollama、火山引擎配置? ​

当前文档只描述源码已落地的调用规格。上述服务如果提供 OpenAI-compatible 接口,可以按兼容端点方式测试;如果需要原生协议适配,应以新增源码适配和测试结果为准。

相关源码 ​

  • snail-ai-models/
  • snail-ai-models/snail-ai-model-chat/snail-ai-model-chat-provider-openai-responses
  • snail-ai-server/snail-ai-server-admin/src/main/java/com/aizuda/snail/ai/admin/controller/
  • snail-ai-starter/src/main/resources/application.yml
  • docs/guide/model/index.md
  • docs/guide/model/provider.md

Apache 2.0 Licensed