本文档由 石墨办公 提供。
AI配置
一、配置前先了解四类能力
| 配置类型 | 用来做什么 | 是否必须配置 |
|---|---|---|
| 基础模型 | 处理对话、写作、总结、改写、问答等文本或多模态任务 | 使 用 AI 功能时通常需要 |
| 图片模型 | 生成图片或编辑图片 | 仅在使用图片生成、图片编辑功能时需要 |
| 联网搜索 | 从外部搜索服务获取互联网信息，为模型补充参考内容 | 仅在使用联网检索功能时需要 |
| Embedding | 将文本转换为向量，用于知识库检索、语义搜索等功能 | 仅在使用知识检索、向量检索功能时需要 |
二、进入 AI 配置
1.
2.
3.
4.
5.
三、先选择要接入的模型服务商
| 模型类型 | 服务商 |
|---|---|
| 基础模型 | 兼容 OpenAI Responses 协议的服务商 |
| 图片模型 | 兼容 OpenAI Image 协议的服务商 |
| 联网搜索引擎模型 | 目前仅支持火山云 |
| Embedding 模型 | 兼容 OpenAI embedding 协议的服务商 |
四、AI 各种模型配置
4.1 基础模型
Provider 配置
| 配置项 | 示例值 | 说明 |
|---|---|---|
| 服务商 | 选择 OpenAI（或兼容 OpenAI Responses 协议） | |
| 选择 OpenAI（或兼容 OpenAI Responses 协议） | ||
| 请求地址 / Base URL | https://myai.com/v1 | 选择你自己的兼容 OpenAI Responses 协议的 AI 网关地址 |
| API Key | sk-I••••haTO | 你的 AI 网关分配给你的 API Key |
| 默认模型 | gpt-5.5 | 兼容 OpenAI Responses 协议的模型 |
stream: true，如果模型供应商不支持流式模式，那么会导致请求失败。模型配置
| 配置项 | 示例值 | 研发说明 |
|---|---|---|
| 状态 | 启用 | 需要启用 |
| 模型 ID | gpt-5.5 | 合法的模型 ID |
| 模型名称 | gpt-5.5 | 和模型 ID 一致即可 |
| 上下文窗口 | 1024000 | 根据实际情况填写 |
| 文本输入 | 启用 | 需要启用 |
| 图片输入 | 启用 | 需要启用 |
4.2 图片模型
图片模型用于图片生成或图片编辑。请填写当前版本实际支持的模型与能力。
| 配置项 | 示例值 | 研发说明 |
|---|---|---|
| 状态 | 启用 | 需要启用 |
| 服务商 | OpenAI（或兼容 OpenAI image 协议） | OpenAI（或兼容 OpenAI image 协议） |
| 模型名称D | gpt-image-2 | 需要兼容 OpenAI image 协议 |
| 请求地址 / Base URL | https://myai.com/v1 | 选择你自己的兼容 OpenAI Responses 协议的 AI 网关地址 |
| API Key | sk-I••••haTO | 你的 AI 网关分配给你的 API Key |
| Features | image-generation, image-edit | 保持默认的 image-generation, image-edit |
4.3 联网搜索模型
| 配置项 | 示例值 | 研发说明 |
|---|---|---|
| 状态 | 启用 | 根据实际需求启用，如果启用需要完善当前配置组中的所有其他条目的值 |
| 服务商 | 火山云 | 目前仅支持火山云 |
| 接口地址 | https://open.feedcoopapi.com/search_api/web_search | 火山云默认的联网搜索地址 |
| API Key | mCmh•••••••• | 找联网搜索服务供应商获取 |
| 超时设置 | 120s | 超过此时间单次联网搜索请求会失败，建议保持 120s 即可 |
4.4 Embedding 模型
| 配置项 | 示例值 | 研发说明 |
|---|---|---|
| 服务商 | OpenAI（或兼容 OpenAI embedding 模型协议） | OpenAI（或兼容 OpenAI embedding 模型协议） |
| Base URL | https://myai.com/v1 | 选择你自己的兼容 OpenAI Responses 协议的 AI 网关地址 |
| API Key | ak-•••••••• | 找 embedding 模型供应商获取 |
| Embedding 模型 | qwen3-embedding:4b | |
| 模型 ID | ||
| Dimension 维度 | 整数值 | 维度和 embedding 模型相关，可以找供应商咨询模型相关的维度参数 |
| 研发确认项 | 内容 |
|---|---|
| 支持的 Embedding 模型 | OpenAI（或兼容 OpenAI embedding 模型协议） |
| 推荐向量维度 | 和 embedding 模型相关 |
| 不同维度是否需要重新构建向量数据 | 需要 |
4.5 GPT 配置完成检查
| 验证项 | 预期结果 | 实际结果 |
|---|---|---|
| 基础模型对话 | 在 AI 会话中输入简单问题 | 模型返回相应结果 |
| 长文本处理 | 输出长文本 | 模型根据长文本内容返回相应结果 |
| 图片输入或图片处理 | 输入图片进行识别 | 可以返回识别后的内容 |
| 联网搜索 | 提示词中让它检索机票或者车票信息 | 可以返回机票或者车票结果 |
| Embedding 向量化 | 在全站搜索中使用关键词进行 AI 检索 | 可以返回预期的命中的内容 |
五、每个配置项的业务含义
5.1 基础模型 Provider 配置项
| 配置项 | 业务含义 | 填错后的常见影响 | 是否必填 |
|---|---|---|---|
| 服务商 | 告诉系统使用哪一种模型适配方式。即使两个服务都兼容相似接口，服务商选项也可能决定请求格式、鉴权方式和返回结果解析方式。 | 可能无法保存、请求格式不匹配或返回内容无法解析。 | 是 |
| 请求地址 / Base URL | 办公套件向模型服务发送请求时访问的入口地址。 | 地址错误时无法连接模型；路径层级错误时可能提示接口不存在。 | 是 |
| API Key | 模型服务用于识别调用方和校验权限的凭证。 | 填写错误、过期或权限不足时通常提示鉴权失败。 | 是 |
| 默认模型 | 当业务功能没有明确指定模型时，系统优先调用的模型。 | 未设置或设置为不可用模型时，部分 AI 功能可能无法调用。 | 是 |
5.2 基础模型配置项
| 配置项 | 业务含义 | 填错后的常见影响 | 是否必填 |
|---|---|---|---|
| 状态 | 控制该模型是否允许被办公套件调用。关闭后，配置可以保留，但业务通常不能继续使用该模型。 | 模型配置正确但状态关闭时，业务仍可能显示不可用。 | 是 |
| 模型 ID | 模型服务接口真正识别的模型名称或唯一标识。 | 与服务端名称不一致时通常提示模型不存在。 | 是 |
| 模型名称 | 在运维平台中展示给管理员看的名称，帮助区分不同模型。 | 名称重复或不清晰时容易选错模型；是否参与实际请求由研发确认。 | 是 |
| 上下文窗口 | 模型一次请求可处理的信息总量，通常会影响可输入文本长度、历史对话长度和输出空间。 | 设置大于模型实际能力时可能请求失败；设置过小时会导致内容被截断或无法提交。 | 是 |
| 文本输入 | 表示该模型是否能够接收文字内容。 | 错误关闭后，文本类功能可能无法选择或调用该模型。 | 是 |
| 图片输入 | 表示基础模型是否能理解用户上传的图片，是多模态输入能力，不等同于生成图片。 | 对不支持图片的模型开启后，请求可能失败；关闭后图片理解功能不可用。 | 是 |
5.3 图片模型配置项
| 配置项 | 业务含义 | 填错后的常见影响 | 是否必填 |
|---|---|---|---|
| 状态 | 控制图片模型是否可以被图片生成或编辑功能调用。 | 状态关闭时，相关图片功能无法使用该模型。 | 是 |
| 服务商 | 决定图片请求使用的接口适配方式。 | 选择错误时可能出现请求参数或返回格式不兼容。 | 是 |
| 模型名称 / 模型 ID | 指定实际调用的图片模型。该字段是展示名称还是请求 ID，需要研发明确。 | 名称与服务端不一致时可能提示模型不存在。 | 是 |
| Base URL | 图片生成或编辑请求发送到的服务地址。 | 地址或路径错误时无法调用图片服务。 | 是 |
| API Key | 调用图片服务使用的鉴权凭证。 | 错误、过期或无权限时会鉴权失败。 | 是 |
| Features | 声明模型支持的图片能力，例如图片生成、图片编辑等。 | 配置了模型不支持的能力时，业务入口可能可见但调用失败。 | 是 |
5.4 联网搜索配置项
| 配置项 | 业务含义 | 填错后的常见影响 | 是否必填 |
|---|---|---|---|
| 状态 | 控制办公套件是否可以调用当前搜索服务。 | 状态关闭时，模型仍可能可用，但无法获取联网搜索结果。 | 否 |
| 服务商 | 指定使用哪种搜索服务及其接口适配方式。 | 选择错误时，请求和结果解析可能不兼容。 | 否 |
| 接口地址 | 发起搜索请求时访问的服务入口。 | 地址错误时联网功能超时或连接失败。 | 否 |
| API Key | 搜索服务使用的鉴权凭证。 | 错误或权限不足时搜索请求会被拒绝。 | 否 |
| 超时设置 | 单次搜索最多等待多长时间，超过后系统停止等待并按失败或无结果处理。 | 设置过短会频繁超时；设置过长会使用户等待时间增加。 | 否 |
5.5 Embedding 配置项
| 配置项 | 业务含义 | 填错后的常见影响 | 是否必填 |
|---|---|---|---|
| Base URL | 文本向量化请求发送到的服务地址。 | 地址错误时无法生成或更新向量数据。 | 否 |
| API Key | Embedding 服务使用的鉴权凭证。 | 错误、过期或无权限时向量化失败。 | 否 |
| Embedding 模型 | 实际负责把文本转换为向量的模型 ID。 | 模型不存在或不匹配时无法生成向量。 | 否 |
| Dimension 维度 | 每条文本最终生成的向量长度，必须与模型实际输出和向量存储配置一致。 | 维度不一致时通常无法写入或检索；更换维度后可能需要重新生成已有向量。 | 否 |
六、推荐配置顺序
1.
2.
3.
4.
5.
6.
7.
8.
七、配置生效规则
| 需要研发确认的问题 | 内容 |
|---|---|
| 保存配置后是否立即生效 | 不是立即生效，需要等待 1-2 分钟 |
| 是否需要重启服务 | 无需重启服务 |
| 新配置对已打开页面是否生效 | 需要重新刷新当前页面 |
| 多个模型之间的选择优先级 | 不支持 |
| 默认模型不可用时是否自动切换 | 不支持 |
八、常见问题排查
| 现象 | 常见原因 | 排查方法 |
|---|---|---|
| 连接模型服务失败 | 请求地址、网络、证书或端口配置异常 | 检查服务地址、DNS、端口、证书和防火墙策略 |
| 提示鉴权失败 | API Key 错误、过期或权限不足 | 确认 API Key 正确，并具备目标模型或服务的调用权限 |
| 提示模型不存在 | 模型 ID 与服务端实际名称不一致 | 确认完整模型 ID，并检查大小写和版本后缀 |
| 文本可用但图片不可用 | 模型不支持图片输入，或图片输入开关未开启 | 核对模型能力和输入开关 |
| 图片功能入口存在但调用失败 | Features 与模型实际能力不一致 | 核对图片模型支持的生成、编辑能力 |
| 联网搜索频繁超时 | 搜索服务较慢、网络不稳定或超时设置过短 | 检查网络延迟、服务性能和超时单位 |
| Embedding 写入失败 | 输出维度与向量存储配置不一致 | 核对模型实际输出维度和存储配置 |
Q&A
1.
2.
修改于 2026-08-28 03:22:01