AI 导购配置
AI 导购基于阿里云百炼的知识库与知识检索服务实现。整体配置流程为：先在阿里云百炼创建知识库、创建知识检索服务并获取 API Key，再回到商城后台的「设置--AI 平台--平台配置」完成对接，最后在「营销--AI 导购」中开启功能并同步商品数据。
一、阿里云百炼创建知识库
1. 进入百炼平台
登录阿里云控制台，在产品列表中找到并进入「大模型服务平台百炼」，在首页点击「全模态企业级知识库」进入知识库工作台。
2. 创建知识库
进入知识库工作台后，在左侧菜单点击「知识管理」，点击右上角「创建」。
按页面提示填写知识库名称与描述，并上传商品、店铺等业务资料（支持 Word、Excel、PDF、JPG、PNG、MP4 等格式，可自动解析）。
3. 配置知识库参数
知识库创建完成后，在「编辑知识库」页面按需配置以下参数：
| 配置项 | 说明 |
|---|---|
| 向量存储类型 | 知识库使用的向量存储方式 |
| 多轮对话改写 | 开启后按多轮对话上下文改写提问 |
| Rank 模型 | 用于结果重排的排序模型，如 qwen3-rerank |
| 排序模型模式 | 可选「问答模式」「相似模式」「自定义高级模式」 |
| 初步向量检索 TopK | 向量检索阶段返回的候选数量 |
| 初步关键词检索 TopK | 关键词检索阶段返回的候选数量 |
| 相似度阈值 | 低于该阈值的召回结果将被过滤 |
| 最终召回最大数量 | 最终返回给模型的知识条目数量 |
| 知识库规格 | 知识库的计费规格，如标准版 |
4. 获取知识库 ID
在「知识管理」列表中，知识库卡片上会显示「ID」，点击复制，后续需粘贴到商城后台的「知识库索引 ID」。
二、创建知识检索服务
1. 新建检索服务
在左侧菜单点击「知识检索」，点击「创建」。
2. 填写服务信息
在「创建检索服务」弹窗中填写服务名称与描述信息，点击「确定」。
| 配置项 | 说明 |
|---|---|
| 服务名称 | 检索服务名称，最多 40 个字符 |
| 描述信息 | 服务用途说明，便于模型理解检索能力，最多 200 个字符 |
3. 接入知识库
进入检索服务的「服务配置」页：
| 配置项 | 说明 |
|---|---|
| 知识库 | 点击「添加」选择上一步创建的知识库，最多可添加 15 个 |
| 知识库路由 | 开启后由模型自动判断使用哪个知识库 |
| 混排模型 | 多知识库结果的混排模型，如 qwen3-rerank |
| 混排模型模式 | 混排模式选择，可选问答模式 |
| 最大召回数量 | 单次检索返回的最大条目数，取值范围 1~20 |
配置完成后点击右上角「发布」。
三、获取 API 与应用 ID
1. 复制应用 ID
发布后切换到「发布渠道」页，页面会生成对应的 API 调用信息。点击「应用ID」右侧的复制图标，复制该 ID，后续填入后台的「Agent ID」。
2. 创建 API Key
在同一页面点击「API KEY」进入 API-KEY 管理页，页面展示按量付费的 Base URL，点击「创建」。
在「创建 API-KEY」弹窗中填写归属业务空间与描述，并设置权限：
| 配置项 | 说明 |
|---|---|
| 归属业务空间 | 该 API Key 所属的业务空间 |
| 描述 | API Key 用途说明，最多 200 个字符 |
| 权限 | 可选「全部」或「自定义」，自定义时可限制访问 IP |
3. 复制接入信息
创建成功后弹出「API快捷接入」窗口，其中包含 API Key 与 Base Url（API Host、OpenAI 兼容地址、DashScope 地址）。点击「复制」或「下载」保存这些信息，关闭后将无法再查看完整 API Key。
四、后台平台配置
登录商城后台，进入「设置--AI 平台--平台配置」，在「当前使用平台」中选择「阿里云百炼」。
「阿里云百炼 使用中」区域需填写以下配置项：
| 配置项 | 说明 |
|---|---|
| API Key | 阿里云百炼知识问答服务的 API Key，仅做服务端使用，不会返回给前端；已保存时留空表示不修改 |
| Workspace ID | 业务空间 ID，形如 llm-xxxxxxxx，用于拼接知识问答域名 |
| Agent ID | 知识检索服务发布后生成的应用（Agent）ID |
| 知识库索引 ID | 知识库 ID，不填则不启用知识库自动同步 |
| 普通生成模型 | 非业务入口的默认对话模型，默认 qwen-plus |
| 普通生成接口地址 | 默认 https://dashscope.aliyuncs.com/api/v1，其他地域或私有化部署时按实际填写 |
| 地域 | 模型服务所在地域，默认 cn-beijing |
| 语音合成模型 | 用于「朗读回复」，默认 qwen3-tts-flash |
| 语音合成音色 | 可选 Cherry、Serena、Ethan，默认 Cherry |
| 语音合成接口地址 | 默认 https://dashscope.aliyuncs.com/api/v1，其他地域或私有化部署时按实际填写 |
| 超时时间（毫秒） | 接口请求超时时间，默认 30000 |
若已下载阿里云百炼的 API 快捷接入文件（CSV），可直接对照文件中字段填入后台：
| CSV 字段 | 对应后台配置项 |
|---|---|
| apiKey | API Key |
| apiHost | 普通生成接口地址 / 语音合成接口地址 |
| workspaceId | Workspace ID |
| openaiCompatible | OpenAI 兼容接口地址（参考） |
| dashScope | DashScope 接口地址（参考） |
| description | 描述信息（参考） |
除上述关键项外，其余配置保持默认即可；若修改了自定义地址，需保证普通生成接口地址与语音合成接口地址的配置一致。填写完成后点击「保存」。
保存成功后页面提示「AI 平台已配置」，此时 AI 业务（导购）均可使用。
五、开启 AI 导购功能
平台配置完成后，进入「营销--AI 导购--导购设置」进行功能开关与运行参数配置。
| 配置项 | 说明 |
|---|---|
| 应用 AI 导购 | 关闭后前端 AI 导购入口降级为本地检索，入口可正常访问 |
| 应用知识库同步 | 关闭后不再执行任何同步任务，定时任务与手动同步均不会执行 |
| 单轮任务数 | 每轮同步最多处理的任务数，默认 20 |
| 最大重试次数 | 失败任务的重试上限，超过上限后标记为失败，默认 5 |
「导购入口」页签用于配置 AI 导购在前端的入口展示相关提示内容。配置完成后点击「保存」。
六、同步商品知识库
进入「营销--AI 导购--知识库同步」，页面顶部可切换同步来源（AI 导购（平台）/ 全部商家（接口入）），并按店铺筛选、搜索店铺名称或店铺 ID。
页面提供「同步批次」「同步任务」两个页签。批次列表字段如下：
| 列名 | 说明 |
|---|---|
| 批次号 | 单次同步任务的批次编号 |
| 数据源 | 本次同步的数据来源，如 mall、front_warehouse |
| 店铺 ID | 数据所属店铺编号 |
| 进度 | 已处理数量与总量、失败数量 |
| 状态 | 全部成功、部分失败、执行中、全部失败、待执行 |
| 触发方式 | 手动同步、自动触发 |
| 完成时间 | 批次执行完成的时间 |
说明：同步任务按店铺维度分批处理，单店每 5 分钟处理一次；失败任务会在每次同步时按「最大重试次数」重试。
七、注意事项
- 阿里云百炼的 API Key 仅在创建时完整展示，请及时复制或下载保存。
- 「Agent ID」对应知识检索服务的应用 ID，「知识库索引 ID」对应知识库 ID，两者不可混填。
- 修改平台配置后需点击「保存」才会生效。
- 若关闭「应用知识库同步」，AI 导购将不会更新商品数据，前端回答内容可能滞后。