Docs
文档目录

快速开始

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

准备工作

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

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

查看流程图大图

1. 创建或选择项目

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

  2. 项目根路径进入平台登记页 /overview/platforms;项目下的 /get-started 是独立的项目引导页,可选择平台或服务端接入。

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

项目引导页中的平台选择

图:2.12.0 环境中的项目引导页;实际选项以部署环境为准。

2. 配置模型

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

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

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

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

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

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

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

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

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

4. 在智能体工作台验证

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

  2. 选择可用的对话模型并按需配置提示词。在知识库选择器中先选择刚创建的知识库,关闭选择器后开启知识检索;配置会自动保存,请等待页面显示保存完成。

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

工作台中的知识库问答结果

图:2.12.0 测试项目使用合成文档问答,并显示知识来源。

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

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 命令参数中。空用户列表也是正常结果。

(
  set +x
  set -o pipefail
  builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | \
    curl --disable --header @- -sS -w '\nHTTP %{http_code}\n' \
      -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
      "${APPBASE_ENDPOINT}/users"
)
unset APPBASE_API_KEY

上述命令保留错误响应体。若请求失败,请核对状态码及响应中的错误信息、目标环境、项目 ID、密钥有效期和权限;不要把含密钥的请求或日志发给他人。

常见问题

相关文档