Docs
文档目录

快速开始

本指南介绍如何创建项目、接入模型、上传文档并在智能体工作台验证知识问答。你可以使用已有组织和项目;页面名称可能随界面语言和部署环境有所不同。

准备工作

快速开始:流程示意,不是运行截图

流程示意,不是运行截图。

查看流程图大图

1. 创建或选择项目

  1. 登录目标环境的控制台,创建或选择组织,然后创建或选择项目。记录项目 ID 和区域,后续请求需要使用实际值。

  2. 进入项目后,项目根路径会跳转到平台登记页 /overview/platforms。旧的 /get-started 路径同样会重定向到该页面。

  3. 如果需要从浏览器应用调用客户端 SDK,在项目总览的平台登记页添加实际使用的域名;仅进行服务端验证时不必为本教程登记浏览器平台。

2. 配置模型

  1. 在项目中打开模型,添加模型供应商。可以选择阿里云百炼(DashScope)预设,也可以选择环境支持的其他供应商。

  2. 填写供应商所需的凭据和连接信息,启用账号实际可用的对话模型与向量模型。模型目录中存在某个名称并不代表当前账号已经开通。

  3. 控制台生成供应商标识;连接名称用于识别配置。请记录实际配置,后续按名称选择模型。

3. 创建知识库并上传文档

  1. 打开知识库,创建知识库并填写名称、可选描述,选择可用的向量模型。知识库标识由控制台生成;向量模型创建后不可更改,维度应与所选模型的实际输出一致。

  2. 选择适合文件的文档解析方式。默认 documentParser 为 vlm,需要选择可用的视觉模型 visionModel;对于适合纯文本解析的文件,也可选择 text。不同解析方式的适用范围和效果不同。

  3. 打开知识库的文档页,上传自己的测试文件。上传窗口默认启用上传后摄取;如果关闭该选项,需要在文档列表中手动发起摄取。等待文档和摄取任务就绪(ready),再进行检索。

  4. 在检索页输入能够由文件回答的问题,检查返回片段及其来源是否与原文一致。如果需要词库,在项目的词库页面创建后,到知识库设置中绑定;词库不是完成本教程的必要条件。

例如,可上传一份包含“项目支持通过知识库检索内部文档。”的纯文本文件,然后询问“项目如何检索内部文档?”。检索结果取决于实际模型、文件和索引状态。

4. 在智能体工作台验证

  1. 打开智能体工作台。首次使用时,先按页面提示启用或初始化工作台。

  2. 选择可用的对话模型并配置提示词。开启知识库检索(Knowledge Search)开关,在出现的选择器中选择刚创建的知识库并保存;部分其他配置会自动保存,请等待页面显示保存完成。

  3. 发送能由测试文件回答的问题,检查最终回答,并在界面提供来源时打开来源核对原文。如果结果不符合预期,先在知识库检索页检查文档状态和召回片段。

工作台的对话结果与引用取决于模型、检索结果和配置;读取工作台配置只能验证配置接口,不能代替一次真实问答。

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、密钥有效期和权限;不要把含密钥的请求或日志发给他人。

常见问题

相关文档

历史界面参考

下图为已登记的历史项目欢迎页,仅供界面演变参考;当前项目入口与操作以本指南及实际控制台为准。

历史项目欢迎页,非当前操作步骤