快速开始
本指南介绍如何创建项目、接入模型、上传文档并在智能体工作台验证知识问答。你可以使用已有组织和项目;页面名称可能随界面语言和部署环境有所不同。
准备工作
可以访问目标环境的控制台,并具有创建或配置项目所需的组织权限。
准备可用的模型供应商凭据,以及该账号有权使用的对话模型和向量模型;具体模型名称和费用以供应商及部署环境为准。
准备一份允许上传的文本文件。下文所有名称均为示例,项目、知识库等标识应使用实际创建后显示的值。
流程示意,不是运行截图。
1. 创建或选择项目
登录目标环境的控制台,创建或选择组织,然后创建或选择项目。记录项目 ID 和区域,后续请求需要使用实际值。
进入项目后,项目根路径会跳转到平台登记页
/overview/platforms。旧的/get-started路径同样会重定向到该页面。如果需要从浏览器应用调用客户端 SDK,在项目总览的平台登记页添加实际使用的域名;仅进行服务端验证时不必为本教程登记浏览器平台。
2. 配置模型
在项目中打开模型,添加模型供应商。可以选择阿里云百炼(DashScope)预设,也可以选择环境支持的其他供应商。
填写供应商所需的凭据和连接信息,启用账号实际可用的对话模型与向量模型。模型目录中存在某个名称并不代表当前账号已经开通。
控制台生成供应商标识;连接名称用于识别配置。请记录实际配置,后续按名称选择模型。
3. 创建知识库并上传文档
打开知识库,创建知识库并填写名称、可选描述,选择可用的向量模型。知识库标识由控制台生成;向量模型创建后不可更改,维度应与所选模型的实际输出一致。
选择适合文件的文档解析方式。默认
documentParser为vlm,需要选择可用的视觉模型visionModel;对于适合纯文本解析的文件,也可选择text。不同解析方式的适用范围和效果不同。打开知识库的文档页,上传自己的测试文件。上传窗口默认启用上传后摄取;如果关闭该选项,需要在文档列表中手动发起摄取。等待文档和摄取任务就绪(
ready),再进行检索。在检索页输入能够由文件回答的问题,检查返回片段及其来源是否与原文一致。如果需要词库,在项目的词库页面创建后,到知识库设置中绑定;词库不是完成本教程的必要条件。
例如,可上传一份包含“项目支持通过知识库检索内部文档。”的纯文本文件,然后询问“项目如何检索内部文档?”。检索结果取决于实际模型、文件和索引状态。
4. 在智能体工作台验证
打开智能体工作台。首次使用时,先按页面提示启用或初始化工作台。
选择可用的对话模型并配置提示词。开启知识库检索(Knowledge Search)开关,在出现的选择器中选择刚创建的知识库并保存;部分其他配置会自动保存,请等待页面显示保存完成。
发送能由测试文件回答的问题,检查最终回答,并在界面提供来源时打开来源核对原文。如果结果不符合预期,先在知识库检索页检查文档状态和召回片段。
工作台的对话结果与引用取决于模型、检索结果和配置;读取工作台配置只能验证配置接口,不能代替一次真实问答。
5. 可选:验证服务端接口
项目总览的 API 密钥页面可创建项目级服务端密钥。只验证下面的用户列表时,授予 users.read;如果还需要读取 /v1/agent-runtime/project/config,另需 agent-runtime.project。按实际用途授予最小权限,勿将服务端密钥放入浏览器代码或提交到仓库。
在本地终端设置实际服务端点和项目 ID。交互式输入密钥不会将密钥放入常用的命令历史;不要录制终端输入或打印密钥。
APPBASE_ENDPOINT="https://your-agentbase.example.com/v1"
APPBASE_PROJECT_ID="your-project-id"
read -r -s -p 'API key: ' APPBASE_API_KEY
printf '\n'检查公开的服务版本:
curl -sS -w '\nHTTP %{http_code}\n' "${APPBASE_ENDPOINT}/health/version"查询项目用户列表;请求使用标准输入传递密钥,避免将其展开到 curl 命令参数中。空用户列表也是正常结果。
printf 'header = "X-Appwrite-Key: %s"\n' "$APPBASE_API_KEY" | \
curl --config - -sS -w '\nHTTP %{http_code}\n' \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
"${APPBASE_ENDPOINT}/users"
unset APPBASE_API_KEY上述命令保留错误响应体。若请求失败,请核对状态码及响应中的错误信息、目标环境、项目 ID、密钥有效期和权限;不要把含密钥的请求或日志发给他人。
常见问题
无法选择模型或调用失败:检查供应商是否启用、凭据和额度是否有效,以及账号是否已开通对应模型。
文档未就绪:检查是否触发摄取、解析方式与文件是否匹配,以及向量模型和视觉模型是否可用;查看失败详情后再重新摄取。
检索不到内容:确认文档和摄取任务均已就绪,检查分块内容与问题,再核对知识库是否已绑定到工作台。
接口返回鉴权错误:确认密钥属于当前项目、尚未过期,并具备所调用接口要求的权限。
相关文档
历史界面参考
下图为已登记的历史项目欢迎页,仅供界面演变参考;当前项目入口与操作以本指南及实际控制台为准。

