连接 Astra DB 内容存储库

连接 Astra DB 内容存储库，支持高性能矢量和混合搜索。运行时，代理会查询 Astra DB 以检索相关内容，从而获得基于上下文的准确结果。

Astra DB 是一种支持向量的数据库，可提高结构化和非结构化数据的检索准确性。 Agent Knowledge 支持以下 Astra DB 搜索类型：矢量搜索、词性或关键词搜索、混合搜索（将矢量搜索和词性搜索结合在一个步骤中以提高准确性）。对于矢量搜索，代理知识支持 Astra DB 客户端嵌入和服务器嵌入。服务器嵌入无需额外调用嵌入模型，即可将来自 watsonx Orchestrate 的查询进行嵌入。代理知识支持对存储在 Astra DB 集合和表格中的非结构化数据和结构化数据进行搜索。

使用以下产品或工具连接 Astra DB 资源库：

Astra DB，在此配置数据库实例。
watsonx.ai (可选），用于管理 IBM 服务的嵌入。要使用第三方嵌入模型，请通过代理开发工具包（ADK）进行集成。如需了解更多信息，请参阅《使用 AI 网关管理自定义 LLM》。

在开始程序之前，请遵守连接 Astra DB 的先决条件。

连接 Astra DB 的前提条件

您必须拥有一个激活的 Astra DB 账户。
在您的账户中配置一个 Astra DB 实例。
创建一个 API 密钥来验证连接。
请确保您拥有创建知识源所需的访问角色。

连接 Astra DB 实例

使用 Astra DB 实例上的数据连接代理：

在代理配置页面，转到知识部分。
单击 " 选择知识 + "。
在 "添加来源 "下，单击 " 新知识 "。
选择 Astra DB > 下一步。
从 Connect Astra DB 提供连接数据。
- URL :输入 Astra DB 实例的端点 URL。
- 端口（可选）：默认情况下，Astra DB 监听端口为 443。只有当实例使用非标准配置时，才输入自定义端口。
填写 API 密钥字段。
单击 " 下一步 "继续。

Astra DB 将数据组织到键空间中，类似于关系系统中的数据库。默认情况下，会自动创建一个密钥空间，但您也可以从 Astra DB 实例中的任何现有密钥空间中进行选择。
选择代理查询的数据类型 ：
- 收集：用于结构化和非结构化数据。
- 表格：用于以行和列存储的结构化数据。
根据您选择的数据类型 ，从集合或表格类型中选择一个选项。
选择嵌入模式。更多信息，请参阅配置嵌入和搜索模式。
选择搜索模式。更多信息，请参阅配置嵌入和搜索模式。
将 Astra DB 字段映射到相应的代理响应字段。更多信息，请参阅制图结果

可选：要配置高级 Astra DB 设置 ，请参阅高级 Astra DB 设置。
单击 " 下一步 "继续。
在知识详情部分、
- Name:输入知识源的显示名称。
- Description:提供简短说明。如需了解更多信息，请参阅向代理提供有关知识的上下文。
保存设置。

返回 Agent Builder 页面。 Astra DB 存储库现已连接。要验证设置，请在代理中运行查询。

更新 Astra DB 设置

更新配置

转到 " 知识 "部分。
单击所选知识源旁边的垂直省略号 (⋮)。
选择编辑详细信息并更新配置。
保存设置。

删除 Astra DB 仓库

删除存储库：

转到 " 知识 "部分。
单击所选知识源旁边的垂直省略号 (⋮)。
单击除去。

配置嵌入和搜索模式

Astra DB 支持多种嵌入和搜索选项，以平衡准确性和性能：


选项	描述	使用时间
矢量搜索	将查询转换为向量，以便进行语义匹配。	最适合长或复杂的查询。
词法搜索	执行传统的基于关键字的匹配。	最适合精确匹配和结构化术语。
混合搜索	结合向量搜索和词法搜索，然后对结果重新排序。	用于实现最高的检索精度。
客户端嵌入	查询首先嵌入 watsonx.ai 或其他嵌入服务，然后发送到 Astra DB。	当您想在 Astra DB 之外管理嵌入时使用。
服务器嵌入	Astra DB 会在搜索过程中自动嵌入查询。	用于简单的一步查询，无需外部嵌入调用。

注：

搜索模式必须与该集合或表在 Astra DB 中的配置保持一致。

映射结果

在“配置结果内容”中，将 Astra DB 字段映射到代理响应：

标题：选择结果标题字段。
正文：选择结果文本的字段。
URL (可选）：选择源链接的字段。

Astra DB 高级设置

配置高级筛选器以完善结果。例如：

返回订单项目未结账的结果：

{"is_checked_out": False}

如果订购的图书未被借出，且图书页数少于 300 页，则返回结果：

    {
        "$and": [
            {"is_checked_out": False},
            {"number_of_pages": {"$lt": 300}},
        ]
    }

过滤器语法遵循 Astra DB 的查询规则。有关集合过滤运算符的详细信息，请参阅 “集合过滤运算符 ”。有关表的过滤运算符的详细信息，请参阅 “表的过滤运算符 ”。

传递上下文变量

您可以通过在 Astra DB 过滤器模板中引用上下文变量来使过滤器动态化。这样就能在运行时根据用户或会话上下文替换值，使查询更加灵活和个性化。

它如何工作

在内容存储库中，设置过滤器并以格式引用上下文变量： {context_var}
当代理运行时，它会获取上下文：
- 运行终点有效载荷，或
- 与会话相关的 JWT 标记
知识运行时会用上下文中的实际值替换过滤器模板中的上下文变量

Astra DB 过滤器替换示例

示例包括：

filter:包含上下文变量引用的模板，在过滤器字段中输入，用于动态替换。
final_filter:用实际值替换上下文变量后的模板。查询会被发送到 Astra DB 进行数据检索。
context_variable:一组键值对，定义了用于替换的上下文变量。

示例：

    filter = '{"product_partNumber": "{part}"}'
    context_variable = {"part": "PS-SL-KIT"}
    final_filter = {"product_partNumber": "PS-SL-KIT"}

    filter = '{"number_of_pages": {"$eq": "{count}"}}'
    context_variable = {"count": 400}
    final_filter  = {"number_of_pages": {"$eq": 400}}

    filter = '{"genres": {"$in": "{genres}"}}'
    context_variable = {"genres": ["ABC", "DEF"]}
    final_filter  = {"genres": {"$in": ["ABC", "DEF"]}}

    filter = '{"borrower": {"$exists": "{borrower}"}}'
    context_variable = {"borrower": False}
    final_filter  = {"borrower": {"$exists": False}}

    filter='{"value": {"$in": [82500, {value}]}}'
    context_variable = {"value": [82400, 165000]}
    final_filter  = {"value": {"$in": [82500, 82400, 165000]}}
    
    filter = '{"product_partNumber": "{part}-SL-KIT"}'
    context_variable = {"part": "PS"}
    final_filter  = {"product_partNumber": "PS-SL-KIT"}

下一步操作

连接到 Astra DB 后，您可以修改版本库连接数据或您为获取文档而提供的设置。

要调整代理使用搜索结果的方式，请参阅编辑搜索结果的设置。
开始通过《使用 Astra DB 构建 watsonx Orchestrate 情境感知型人工智能代理》教程深入了解 Astra DB。