执行 RAG 操作

向 RAG 账户指定的 AI 模型服务器上的 RAG 空间发送提示，或从 RAG 空间中添加和删除数据。

另请参阅 

选项 

  • RAG 账户名称是此脚本步骤所使用的 RAG 账户的文本表达式。在当前文件中，使用配置 RAG 账户脚本步骤设置账户，并在此脚本步骤运行之前随时为其分配此名称。

  • 空间 ID 是一个文本表达式，用于指定在指定的 RAG 账户中工作的 RAG 空间的唯一 ID。

  • 操作指定在 RAG 空间上执行的操作类型。此选项控制脚本步骤中其他选项的可用性。选择：

    • “添加数据”将文档（文本数据或 PDF 文件）添加到 RAG 空间。

    • “发送提示”发送提示来查询 RAG 空间并获得 AI 生成的响应。

    • “删除数据”从 RAG 空间中删除文档。

当“操作”为“添加数据”时可用的其他选项：

  • “RAG 数据”指定要添加到 RAG 空间的文档：

    • “来自文本”通过同步传输的文本表达式直接添加文本。

    • “来自文件”添加给定路径的 PDF 文件，同步传输。

    • “来自文件（Async）”添加给定路径的 PDF 文件，异步传输（最适合大文件）。

    • “来自容器”从容器字段添加 PDF 文件，同步传输。

    • “来自容器（Async）”从容器字段添加 PDF 文件，异步传输（最适合大型文件）。

  • “输入文件”指定 PDF 文件的一个或多个路径列表。脚本步骤会搜索列表，并添加它成功找到的第一个 PDF 文件。路径必须使用 image 路径前缀之一。请参阅创建文件路径。

  • “容器字段”指定存储要添加的 PDF 文件的容器字段。

  • 检测竖排文字可提升对包含竖排文字（此类文字常见于日本文学作品、报纸、政府文件及学术论文中）的 PDF 文件的文本提取效果。当RAG 数据设置为“来自文本”时，此选项不可用。

  • 每文本块的令牌数是一个数值表达式，用于指定在向 RAG 空间添加文本或 PDF 文件时，每个文本块应包含的令牌数量。有效值为 75 到 512。如果未指定该值或将其设置为 0，则将使用管理控制台中为 AI 模型服务器配置的值（默认为 200 个令牌）。

  • 响应目标用于指定存储 AI 模型服务器针对所添加文档返回的 JSON 对象的字段或变量。请参阅描述。

当操作为“发送提示”时，可用的附加选项如下：

  • “发送提示”的值是自然语言用户提示或问题的文本表达式。

  • “AI 账户名称”是用于生成响应的 AI 账户名称的文本表达式。在当前文件中，使用配置 AI 账户脚本步骤设置此账户，并在此脚本步骤运行之前随时为其分配此名称。

  • 模型是要使用的文本生成模型的名称。将模型名称指定为文本表达式。有关支持的模型，请参阅 FileMaker 技术规格。

  • “流”控制响应的交付方式：

    • 开：检索响应并进行递增传递（逐字或逐短语）。这可让 FileMaker 客户端响应更快。

    • 关：在可用之前检索整个回复。这可能会导致 FileMaker 客户端在等待完整回复时出现无响应。

  • 提示模板名称指定使用配置提示模板脚本步骤配置的自定义提示模板的名称。此选项用于设计额外的提示，以帮助从 AI 模型获得最佳回复。

  • 响应目标指定要存储模型响应的字段或变量。

  • 参数是 JSON 对象的文本表达式，可以包括：

    • 在发送请求之前处理和删除的 FileMaker 客户端参数：

      CURLOPT_TIMEOUT 设置完成请求的最长时间（以秒为单位）。值必须是非负整数。例如：{"CURLOPT_TIMEOUT": 30}。如果此时没有响应，FileMaker 客户端将取消请求，此脚本步骤将返回错误代码 1629（“连接超时”）。

    • 仅在本脚本步骤执行期间，这些 AI 模型服务器参数会覆盖管理控制台中已配置的设置。如果未指定，将使用管理控制台中设置的值。在将 JSON 对象中包含的任何其他参数直接传递给模型提供商之前，这些参数将被处理和删除。

      详情请参阅“说明”。

    • 模型提供商特定参数与提示一起直接传递给模型提供商。例如：{"温度": 0.7，“种子”：42}.

      注释  有关您正在使用的模型支持的参数和值，请参阅模型提供商的文档。

当操作为“删除数据”时，可用的附加选项如下：

  • “参数”是包含 id 键的 JSON 对象的文本表达式，其值是要从指定的 RAG 空间中删除的文档 ID 数组。例如：

    复制 
    {"id" : ["5f7677a0-3258-55a3-bc86-737005cb3574", "f95d4266-66cd-5b50-a01b-07a4dd66c501"]}

    添加文档时在响应目标中返回的文档 ID 可被存储起来，后续用于删除该文档。或者，要获取 RAG 空间中所有文档的 ID，请使用 GetRAGSpaceInfo函数。

兼容性 

产品 是否支持
FileMaker Pro 是
FileMaker Go 是
FileMaker WebDirect 是
FileMaker Server 是
FileMaker Cloud 是
FileMaker Data API 是
自定义 Web 发布 是

原始版本 

22.0

说明 

此脚本步骤允许您在 Claris AI 模型服务器上创建和管理文档（文本数据和 PDF 文件）的知识缓存。然后，您可以使用一种名为检索增强生成 (RAG) 的技术来利用此缓存。运用这种技术，脚本步骤会将一个提示或问题，连同从知识缓存中检索到的最相关事实信息一并发送给 AI 模型，从而提高模型响应的可靠性和准确性。

“操作”选项决定此脚本步骤的作用。

添加数据操作

此操作从指定的文档中添加 RAG 数据：文本（作为任何文本表达式）、按路径添加 PDF 文件或者来自当前或相关记录中的容器字段的 PDF 文件。流程遵循以下步骤：

  1. 脚本步骤将文档发送到 AI 模型服务器。

    如果添加 PDF 文件，脚本步骤将同步或异步发送文件，具体取决于“RAG 数据”选项。如果同步发送，在文件传输完成之前，脚本不会继续下一步。如果异步发送，则在文件传输过程中（最适合大文件），脚本将继续进行下一步，允许 FileMaker 客户端保持对用户交互的响应。

  2. AI 模型服务器为文档分配 ID，然后对其进行处理：

    • 如果文档是 PDF 文件，服务器仅从 PDF 文件中提取文本。然后，提取出的文本会以与使用“来自文本”选项添加的文本相同的方式进行处理。

    • 服务器会根据每文本块的令牌数选项（若已指定）或管理控制台中配置的块大小，将文本拆分为多个块。

      如果文本采用 JSONL（JSON 行格式，即每行均为一个有效的 JSON 对象）格式，服务器会自动识别该格式，并将每一行视为一个独立的语义单元：每行会单独进行分块处理，但各行绝不会被合并在一起。这有助于提高从 FileMaker 表等结构化数据中检索内容的准确性。在 FileMaker 表中，每条记录可格式化为单独一行 JSON 数据，采用此方式能确保记录边界得以保留。

    • 最后，服务器使用为服务器上的 RAG 配置的文本嵌入模型获取所有块的嵌入向量。

  3. 如果指定了响应目标，AI 模型服务器会返回一个 JSON 对象，其中包含所添加文档的文档 ID 和元数据。这允许您存储文档 ID 以供以后使用（例如删除文档）。

    返回的 JSON 对象包含以下键：

    • id：AI 模型服务器分配为十六进制编码的通用唯一标识符 (UUID) 的文档 ID。有关 ID 格式的更多信息，请参阅“注释”。

    • model：AI 模型服务器用于为文档生成嵌入向量的嵌入模型。

    • rag_space_id：文档添加到的 RAG 空间的 ID。

    • result 或 error：

      • result：未出现错误时已添加文档的状态。对于成功同步传输的文档，值为"ok"。对于异步传输的文档，该值是一个包含空间 ID 和缓存文件名的字符串，因为该过程尚未完成。

      • error：AI 模型服务器遇到错误时的错误消息字符串。

    • text 或 file，具体取决于“RAG 数据”的选项：

      • text：使用“来自文本”选项为 RAG 数据添加文档时的文本内容。

      • file：使用文件或容器选项为 RAG 数据添加 PDF 文件时的文件名。

    • usage：文档同步传输时的令牌使用信息。返回的 JSON 对象是 {"prompt_tokens":<number>, "total_tokens":<number>}，其中 prompt_tokens 是输入中的令牌数（嵌入的文本块），total_tokens 是处理的令牌总数。如果 AI 模型服务器设置为不记录令牌使用情况，则不会返回令牌计数。

    注释  对于异步传输的文档，rag_space_id、model 和 usage 键返回"N/A"，因为这些值在处理完成之前不可用。

发送提示操作

此操作将用户提示发送到 AI 模型服务器，从指定的 RAG 空间获取最相关的数据，然后将用户提示与提示模板和 RAG 内容一起发送到 AI 模型。流程遵循以下步骤：

  1. 脚本步骤会将由“发送提示”所指定的提示内容以及“空间 ID”一并发送至由“RAG 账户名称”所指定的 AI 模型服务器。

  2. AI 模型服务器获取提示的嵌入向量，在指定的 RAG 空间中对提示进行语义搜索，然后将 RAG 结果返回到脚本步骤。

    RAG 结果是从 RAG 空间中检索出的相关性最高的 N 个文档块（以文本形式呈现），其中 N 值可在管理控制台中配置，也可通过下方的参数选项进行覆盖设置。

  3. 脚本步骤将提示、提示模板、模型参数和 RAG 结果发送到 AI 账户名称和模型指定的模型。

  4. 模型返回脚本步骤存储在“响应目标”中的响应。

AI 模型服务器参数

对于参数选项，可以使用以下专属于 AI 模型服务器的键值对，来调整此脚本步骤的行为。如已指定，这些值将覆盖管理控制台中设置的值。当不同的提示需要不同级别的精度或上下文大小时，这很有用（例如，查询大文档集而不是小文档集）。如果未指定键，则使用管理控制台中配置的值。

参数键

说明

值范围

similarity_threshold

被纳入上下文的 RAG 结果所需满足的最低余弦相似度得分。更高的值返回的结果更少，但更相关。

-1 到 1

num_top_ranked_results

发送至 AI 模型上下文中所包含的排名靠前的文档块的最大整数数量。值为 0 则不包含 RAG 内容。

1 到 100

例如，这个 JSON 对象在“参数”选项中设置了以下键：

复制 
{
    "similarity_threshold" : .5,
    "num_top_ranked_results" : 10
}

删除数据操作

此操作会从 RAG 空间中删除文档。如果在“参数”选项中指定，则仅删除指定文档；否则，RAG 空间中的所有文档都将删除。

注释  从 RAG 空间中删除文档无法撤销。请务必将原始文件保留在其他地方，以防您需要再次添加它们。

注释 

  • 在使用此脚本步骤之前，必须使用配置 RAG 账户脚本步骤配置 RAG 账户。

  • 对于“发送提示”操作，还必须使用配置 AI 账户脚本步骤配置 AI 账户。

  • 使用“添加数据”操作无法处理具有加密或密码保护的 PDF 文件。

  • RAG 空间是持久的，将保留其文档直到使用“删除数据”操作明确删除。

  • 如果您添加与 RAG 空间中已有的文件名相同的 PDF 文件，则会删除现有的 PDF 文件，并使用新的文档 ID 添加新的 PDF 文件。无论是通过路径还是容器字段添加 PDF 文件，这种行为都是一样的。

  • 在 AI 模型服务器的 26.0.1 版本之前添加到 RAG 空间的文档具有数字文档 ID（例如，1、2、3）。从版本 26.0.1 开始，文档 ID 是 UUID 字符串（例如，"5f7677a0-3258-55a3-bc86-737005cb3574")。在处理包含 ID 格式变更前后所添加文档的 RAG 空间时，您的脚本应能同时兼容这两种文档 ID 格式。

    请参阅示例 3。

  • 如果您指定提示模板名称，则此脚本步骤将使用通过配置提示模板脚本步骤设置的模板。提示模板可使用诸如 :question: 这样的常量（会被替换为 “发送提示” 的值），以及 :context:（会被替换为来自 RAG 空间的、经 RAG 检索到的文档片段）。

  • 对于“每个文本片段的标记数”这一选项：

    • 较大的片段尺寸能保留更多上下文信息，但可能会降低检索的精准度。较小的片段尺寸能提高精准度，但可能会丢失上下文信息。对于日语、中文或韩语等语言，由于分词后每个标记对应的字符数较少，因此固定数量的标记所涵盖的文本内容会显著减少，建议采用较大的数值（例如 250 到 300）。

    • 要更改 RAG 空间中现有文档的片段大小，必须先将文档从该 RAG 空间中移除，然后以新的片段大小重新添加。

    • 如果指定的值超出有效范围，此脚本步骤将返回错误代码 887（“无效的 RAG 空间操作” ）。

  • AI 响应的质量取决于模型以及添加到 RAG 空间的文件的相关性和质量。

  • 在 FileMaker WebDirect 中，当此脚本步骤使用“添加数据”操作，并且“RAG 数据”为“来自文件”或“来自文件（Async）”时，将打开“插入”对话框，供用户选择要上传的 PDF 文件；“输入文件”选项被忽略。

示例 1 - 将文本添加到 RAG 空间

将文本内容添加到客户知识库的 RAG 空间中。

复制 
配置 RAG 账户 [ RAG 账户名称: "customer-support-rag-account" ; 端点: "https://myserver.example.com/llm/v1/" ; API 密钥: "eyJh..." ; 验证 SSL 证书 ]

执行 RAG 操作 [ RAG 账户名称 : "customer-support-rag-account" ; 空间 ID: "knowledge-base" ; 操作: 添加数据 ; RAG 数据: 来自文本 ; "处理退货与换货的客户支持政策及流程..." ]

示例 2 -发送查询 RAG 空间的提示

发送提示以查询与示例 1 相同的 RAG 空间，并将响应存储在字段中。

脚本设置 RAG 账户和 AI 账户以使用 AI 模型服务器。

$parameters 变量中，将 similarity_threshold 设置为 0.6，以确保仅纳入高度相关的 RAG 结果；同时将 num_top_ranked_results 设置为 5，以将上下文限制为相关性最高的前 5 个文档片段，此设置会覆盖管理控制台中配置的默认值。它还包括 CURLOPT_TIMEOUT，如果没有响应，则在 30 秒后取消请求。

发送提示时，该脚本会将 temperature 和 max_tokens 参数发送给模型，用于生成响应，并将响应流式传输至某个字段。

复制 
配置 RAG 账户 [ RAG 账户名称: "customer-support-rag-account" ; 端点: "https://myserver.example.com/llm/v1/" ; API 密钥: Global::RAG_API_Key ; 验证 SSL 证书 ]

配置 RAG 账户 [ 账户名称: "AI_Model_Server" ; 模型提供商: 自定义 ; 端点: "https://myserver.example.com/llm/v1/" ; API 密钥: Global::Text_Gen_API_Key ; 验证 SSL 证书 ]

设置变量 [ $parameters ; 值: 
  JSONSetElement ( "{}" ;
    [ "temperature" ; .3 ; JSONNumber ] ;
    [ "max_tokens" ; 500 ; JSONNumber ] ;
    [ "similarity_threshold" ; .6 ; JSONNumber ] ;
    [ "num_top_ranked_results" ; 5 ; JSONNumber ]
  )
]

执行 RAG 操作 [ RAG 账户名称: "customer-support-rag-account" ; 空间 ID: "knowledge-base" ; 操作: 发送提示 ; 发送提示: "有缺陷产品的退货规定是什么?" ; AI 账户名称: "AI_Model_Server" ; 模型: Global::ModelName ; 流: 打开 ; 响应目标: Customer_Support::AI_Response ; 参数: $parameters ]

Customer_Support::AI_Response 字段中可能的结果以“有缺陷产品的退货政策允许您在 14 个日历日内退货”开头。

示例 3 - 从 RAG 空间中添加和删除 PDF 文件

将名为 Policies.pdf 的 PDF 文件添加到 RAG 空间中，然后将其删除。

配置在 AI 模型服务器上使用的 RAG 账户后，脚本通过指定文件路径将 Policys.pdf 文件添加到 RAG 空间中。在删除文件之前，脚本必须找到添加文件时分配的文档 ID。文档 ID 由响应目标返回，并存储在 $ragAddResponse 中。例如：

复制 
{
  "file": "Policies.pdf",
  "id": "f95d4266-66cd-5b50-a01b-07a4dd66c501",
  "model": "multi-qa-MiniLM-L6-cos-v1",
  "rag_space_id": "knowledge-base",
  "result": "ok",
  "usage": {
    "prompt_tokens": 3803,
    "total_tokens": 3803
  }
}

首先，脚本从 $ragAddResponse 中获取文档 ID，并将其存储在 $id 变量中。同时，脚本使用 JSONGetElementType函数获取该 ID 的数据类型，并将其存储在 $idType 变量中。对于 UUID，数据类型会是 JSONString；对于数字 ID，数据类型则是 JSONNumber（ID格式的详细信息见备注）。

接下来，脚本构建 $idArrayToRemove 变量，该变量是一个 JSON 对象，包含一个 id 键，其值是一个数组，数组中包含要删除的文档 ID。在将 ID 添加到数组时，脚本会使用 $idType 以保留 $ragAddResponse 中的原始数据类型。这种方法确保无论 AI 模型服务器使用哪种 ID 格式，脚本都能正确运行。

最后，脚本调用“执行 RAG 操作”，将参数 选项设置为 $idArrayToRemove，以删除相关数据。

复制 
配置 RAG 账户 [ RAG 账户名称: "customer-support-rag-account" ; 端点: "https://myserver.example.com/llm/v1/" ; API 密钥: Global::RAG_API_Key ; 验证 SSL 证书 ]

执行 RAG 操作 [ RAG 账户名称: "customer-support-rag-account" ; 空间 ID: "knowledge-base" ; 操作: 添加数据 ; RAG 数据: 来自文件 ; "Policies.pdf" ; 响应目标: $ragAddResponse ]

设置变量 [ $id ; 值: JSONGetElement ( $ragAddResponse ; "id" ) ]
设置变量 [ $idType ; 值: JSONGetElementType ( $ragAddResponse ; "id" ) ]


设置变量 [ $idArrayToRemove ; 值: 
  JSONSetElement ( "{}" ; "id" ; 
    JSONSetElement ( "[]" ; 0 ; $id ; $idType ) ; 
    JSONArray 
  ) 
]

执行 RAG 操作 [ RAG 账户名称: "customer-support-rag-account" ; 空间 ID: "knowledge-base" ; 操作: 删除数据 ; 参数: $idArrayToRemove ]

示例 4 - 添加具有不同块大小的文档

将英文和日文文档添加至同一个 RAG 空间，并针对每种语言采用经优化的不同片段大小。

对于英文技术文档，脚本采用较小的片段大小（150 个标记），以便精确检索特定技术细节。

对于日文监管文档，脚本则采用较大的片段大小（300 个标记），因为日文分词后每个标记对应的文本段较短，需要更多标记才能保留足够的上下文信息。此外，脚本还启用了 “检测竖排文本” 选项，以改善从该 PDF 文件中提取竖排文本的效果。

复制 
配置 RAG 账户 [ RAG 账户名称: "product-docs-rag-account" ; 端点: "https://myserver.example.com/llm/v1/" ; API 密钥: Global::RAG_API_Key ; 验证 SSL 证书 ]

执行 RAG 操作 [ RAG 账户名称: "product-docs-rag-account" ; 空间 ID: "product-knowledge" ; 操作: 添加数据 ; RAG 数据: 来自文件 ; "TechnicalSpecs_EN.pdf" ; 每个文本片段的标记数: 150 ]

执行 RAG 操作 [ RAG 账户名称: "product-docs-rag-account" ; 空间 ID: "product-knowledge" ; 操作: 添加数据 ; RAG 数据: 来自文件 ; "Regulations_JA.pdf" ; 检测竖排文本 ; 每个文本片段的标记数: 300 ]

示例 5 - 将记录添加为 JSONL 文本

以 JSONL 格式将 FileMaker 表中的 FAQ 记录添加至 RAG 空间，其中每行代表一条完整的 FAQ 记录。

脚本遍历 FAQ 表中的记录，构建一个 JSONL 格式的文本字符串，其中每行都是一个 JSON 对象，包含问题 ID、问题及答案。当将此 JSONL 格式的文本添加至 RAG 空间时，AI模型服务器会自动检测该格式，并将每行（即每条 FAQ 记录）视为一个独立的语义单元，从而保留记录边界并提高检索准确率。

复制 
配置 RAG 账户 [ RAG 账户名称: "customer-support-rag-account" ; 端点: "https://myserver.example.com/llm/v1/" ; API 密钥: Global::RAG_API_Key ; 验证 SSL 证书 ]

设置变量 [ $jsonlText ; 值: "" ]
转到布局 [ "FAQ" (FAQ) ; 动画: 无 ]

转到记录/请求/页面 [ 第一步 ]
Loop [ 刷新: 始终 ]
  设置变量 [ $jsonLine ; 值: 
    JSONSetElement ( "{}" ;
      [ "id" ; FAQ::QuestionID ; JSONString ] ;
      [ "question" ; FAQ::Question ; JSONString ] ;
      [ "answer" ; FAQ::Answer ; JSONString ]
    )
  ]
  设置变量 [ $jsonlText ; 值: $jsonlText & $jsonLine & ¶ ]
  转到记录/请求/页面 [ 下一步; 最后一步后退出: 打开 ]
End Loop

执行 RAG 操作 [ RAG 账户名称: "customer-support-rag-account" ; 空间 ID: "knowledge-base" ; 操作: 添加数据 ; RAG 数据: 来自文本 ; $jsonlText ; 响应目标: $ragResponse ]

生成的 $jsonlText 变量包含 JSONL 格式的文本，例如：

复制 
{"id":"001","问题":"你们的退货政策是什么?","回答":"物品可以在30天内退货..."}
{"id":"002","问题":"我如何跟踪我的订单?","回答":"您可以使用跟踪编号跟踪您的订单..."}{"id":"003","question":"你们国际发货吗?","回答":"是的，我们运往全球100多个国家..."}

若某行内容足够短，AI 模型服务器会将其作为一个单独的片段处理。 若某行内容超出每个文本片段的标记数限制，则该行会被拆分为多个片段。 由于各行内容绝不会合并处理，因此在查询 RAG 空间时，检索到的片段将仅包含来自单条 FAQ 记录的内容，从而更便于确定是哪条记录提供了相关信息。

相关主题