一、预期目标
二、前置条件与准备工作
- 阿里云国际站账号：已完成企业主体认证的阿里云国际版账号。若绑定海外信用卡遇到障碍，可咨询合作伙伴翼龙云（Yilongcloud），协助梳理开户事项，提供多元化充值方案。
- 创建业务空间（Workspace）：进入百炼控制台，新建业务空间，根据业务面向区域选择部署范围（国际 / 欧盟 / 美国）。所有后续操作全部在该业务空间内完成。
- 开通百炼服务：进入对应业务空间，开通百炼（Model Studio）产品。
- 生成 APIKey：如需外部业务系统对接，在当前业务空间的「API Key 管理」生成密钥并妥善保存；注意：该密钥仅对本业务空间生效，不能跨空间复用。
权限提示：如使用 RAM 子账号操作，除百炼访问权限外，必须额外授予AliyunBailianDataFullAccess知识库数据权限，否则会出现检索 403、召回为空问题。
重要前置提示：
阿里云国际百炼以业务空间（Workspace）为隔离单元，知识库、Agent、APIKey 全部归属业务空间；APIKey 绑定对应业务空间 + 地域，跨业务空间 / 跨地域调用会鉴权 401/403。
- 知识库向量存储创建即按时长计费，无访问也产生费用；仅仅停用 Agent 不会停止计费，必须删除知识库资源才能关闭向量存储扣费阿里云开发…。
- 数据合规：业务面向欧盟、北美，需要在对应地域创建业务空间选择匹配部署范围；选择 “国际” 部署范围时知识库数据存储于新加坡，要满足当地数据驻留法规docs.aliyu…。
- 知识库标准版固定仅支持 1QPS 检索，生产高并发业务需要升级旗舰版 RCU 规格，避免并发下检索超时报错。
三、核心实操步骤
步骤一：数据准备与知识库构建
- 文档预处理
- PDF 扫描图片类文件，尽量提前做 OCR 识别，低清晰度扫描件会造成解析质量差，RAG 效果大幅下降。
- 表格文件优先使用 XLSX 格式；国际百炼不支持直接导入 CSV，CSV 需要转换为 XLSX，表格文件必须携带表头。
- 上传文档：进入业务空间「数据管理」，点击导入数据，上传企业文档，等待文档解析任务执行完成；务必查看任务状态，解析失败的文档不会参与检索。
- 创建知识库：进入「知识库」→创建知识库，填写名称，选择 Embedding 向量化模型（如textembeddingv2），关联已经解析完成的数据源。
分块策略配置参考
| 数据格式 | 适用场景 | 推荐分块策略 | 预期效果 |
| TXT / Markdown | 规章制度、技术文档、代码文档 | 按段落 / 标题语义智能分块 | 检索精准，文档结构还原度高 |
| 行业报告、产品手册 | 开启 OCR，500800 Token，重叠率 10%20% | 保留上下文，适配复杂排版文档 | |
| Word(DOCX) | 合同、内部办公长文档 | 按标题层级智能分块 | 长文档结构清晰，切片逻辑合理 |
| XLSX 表格 | FAQ、参数对照表 | 按行解析，开启表头拼接，每行生成独立切片 | 问答匹配度提升，字段含义不丢失 |
注意：分块策略在知识库创建后不可修改，前期需要做好参数调试。
步骤二：创建 RAGAgent 智能体
- 新建应用：业务空间「应用中心」，选择「创建应用」，选用智能体（Agent）模板。
- 基座模型选择：模型配置区选择 QwenMax / QwenPlus（以国际业务空间模型广场实际可用列表为准）。
- 绑定知识库：开启「知识检索」模块，选择上一步建好的知识库。
- System Prompt 系统提示词示例
你是企业内部业务助手，回答必须严格参考检索返回的知识库内容。
如果知识库没有匹配信息，请直接回复“未找到相关信息”，禁止编造内容。
回答结尾带上文档来源引用标记，例如【来源：文档名称.pdf】。
步骤三：参数调优
- Temperature 温度：企业知识库问答建议设置10.3，降低模型随机编造，保障回答严谨。
- 检索参数：
- TopK：普通问答 35；做总结、对比、列举类复杂业务问题，调高至 610，不要超过 20 上限。
- 相似度阈值：一般60.7，过滤低相关性切片。
- 开启最大拼装长度限制，防止召回切片总 Token 超出模型上下文上限，避免切片被强制截断。
四、连接验证测试
配置页面右侧测试窗口输入业务测试问题，例如：如何申请内部测试服务器？ 预期正常结果：
- Agent 输出来自知识库内的真实流程内容；
- 回答末尾输出文档来源标记，支持查看匹配文档切片。
异常现象：检索召回为空、返回 “未找到相关信息”，优先排查：
- 文档导入任务状态是否解析成功；
- 知识库是否正确绑定；
- 相似度阈值设置是否过高；
- RAM 子账号是否授予知识库数据权限；
- 是否操作错其他业务空间。
五、常见问题排错（FAQ）
Q1：阿里云国际百炼如何搭建 RAG 智能体？ A：先创建对应地域业务空间；数据管理上传文档并等待解析完成；创建知识库完成向量化；应用中心新建 Agent，绑定知识库，设置系统提示词与检索参数，完成调试测试。
Q2：百炼国际知识库支持哪些文件格式？ A：支持 PDF、DOCX、TXT、Markdown、XLSX；不直接支持 CSV，CSV 需要转 XLSX，表格文件必须带表头；单文件存在大小、页数上限，参考官方配额文档。
Q3：调用 API 出现 403、检索结果为空怎么排查？ A：①确认操作在正确业务空间；②确认文档解析任务成功；③RAM 子账号检查AliyunBailianDataFullAccess权限；④调低相似度阈值；⑤检查 APIKey 为本业务空间生成的密钥。
Q4：RAG 检索效果差，回答不准确如何调优？ A：1. 源文档清洗，PDF 扫描件提前 OCR；2. 调整分块大小、重叠率；3. 调整 TopK、相似度阈值，开启拼装长度限制；4. 优化 System Prompt，强化 “不允许编造” 约束；5. 使用知识库调试工具单独测试检索切片质量。
Q5：百炼 RAG 相关计费包含哪些？ A：包含基座模型 Token 消耗、Embedding 向量化 Token 消耗、知识库向量存储按时长计费、检索调用费用；即使不调用 Agent，知识库存在就会产生存储费用，具体以阿里云国际计费文档为准。
Q6：测试完毕如何彻底停止所有计费？ A：停用 / 删除 Agent 应用不等于关闭知识库计费；需要进入知识库页面删除测试知识库，同时清理数据管理内无用文档，再前往费用中心核对账单。
六、测试完成资源清理（必做）
重点提醒：仅删除 Agent 不会停止向量存储计费，知识库资源必须手动删除。
- 删除测试 Agent 应用；
- 删除不再使用的知识库（向量存储计费随知识库删除停止）；
- 在数据管理清理测试文档；
- 前往费用中心，核对百炼相关计费项，确认无遗留资源。