本页面上的部分或全部信息可能不适用于 Cloud de Confiance by S3NS。如需了解详情，请参阅与 Google Cloud 的区别。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

将数据注入与 RAG 引擎搭配使用

本页面介绍了如何使用受支持的数据源（例如 Cloud Storage、Google 云端硬盘、Slack、Jira 或 SharePoint）执行数据注入，以及如何将这些数据与 RAG 引擎搭配使用。ragFiles.import 方法可为这些数据源提供数据连接器。

RAG 支持的数据源

支持以下数据源：

上传本地文件：使用 upload_file 进行单文件上传（最多 25 MB），这是一个同步调用。
Cloud Storage：从 Cloud Storage 导入文件。
Google 云端硬盘：从 Google 云端硬盘导入目录。

必须向服务账号授予正确的权限才能导入文件。否则，系统不会导入任何文件，也不会显示任何错误消息。如需详细了解文件大小限制，请参阅支持的文档类型。

如需进行身份验证并授予权限，请执行以下操作：
1. 转到Cloud de Confiance by S3NS 项目的 IAM 页面。
2. 选择包括 Google 提供的角色授权。
3. 搜索 Agent Platform RAG Data Service Agent 服务账号。
4. 点击云端硬盘文件夹上的共享，然后与服务账号共享。
5. 向服务账号授予 Google 云端硬盘文件夹或文件的 Viewer 权限。Google 云端硬盘资源 ID 可在网址中找到。
Slack：使用数据连接器从 Slack 导入文件。
Jira：使用数据连接器从 Jira 导入文件。

数据去重

如果多次导入同一文件且未进行任何更改，系统会跳过该文件，因为该文件已存在。因此，response.skipped_rag_files_count 是指在导入过程中跳过的文件数量。

如果满足以下条件，系统会跳过某个文件：

文件已导入。
该文件未更改。
该文件的分块配置未更改。

了解导入失败

为了帮助您了解导入失败的原因，本部分将介绍对导入请求的响应中的元数据，以及数据接收器（即您要导入的数据的目标位置）。

响应元数据

您可以使用 response.metadata（SDK 中的一个响应对象）查看导入结果、请求时间和响应时间。

导入结果接收器

在 SDK 中，import_result_sink 是一个可选的函数参数，可以设置为有效的字符串值。

如果提供了 import_result_sink，则成功和失败的文件结果会写入接收器。将所有结果写入接收器有助于您了解为什么某些文件可能无法导入，以及哪些文件未导入。

import_result_sink 必须是 Cloud Storage 路径或 BigQuery 表。

如果 import_result_sink 是 Cloud Storage 路径，则应使用 gs://my-bucket/my/object.ndjson 格式，并且该对象不得存在。导入作业完成后，Cloud Storage 对象的每一行都包含一个 JSON 对象，其中包含操作 ID、创建时间戳、文件名、状态和文件 ID。
如果 import_result_sink 是 BigQuery 表，则应使用 bq://my-project.my-dataset.my-table 格式。表不必存在。如果该表不存在，系统会创建表。如果表存在，则验证架构。首次提供 BigQuery 导入结果接收器时，您将提供一个不存在的表；否则，您可以重复使用现有表。

从 Cloud Storage 或 Google 云端硬盘导入文件

如需将 Cloud Storage 或 Google 云端硬盘中的文件导入到语料库中，请执行以下操作：

创建 RAG 语料库。如需了解详情，请参阅方法：ragCorpora.create。
如需从 Cloud Storage 或 Google 云端硬盘导入文件，请使用 ragFiles.import 方法。

系统会自动检查文件的路径、文件名和 version_id。version_id 是使用文件内容计算得出的文件哈希，可防止文件重新编制索引。

如果具有相同文件名和路径的文件进行了内容更新，系统会重新编制该文件的索引。

从 Slack 导入文件

如需将 Slack 中的文件导入到语料库中，请执行以下操作：

创建语料库，这是一种索引，可对您的数据进行结构化和优化，以便进行搜索。如需了解详情，请参阅方法：ragCorpora.create。
通过 Slack 频道 ID 获取 CHANNEL_ID。
创建并设置一个应用，以便与 RAG 引擎搭配使用。
1. 在 Slack 界面的添加特性和功能部分中，点击权限。
2. 添加以下权限：
  - channels:history
  - groups:history
  - im:history
  - mpim:history
3. 点击安装到工作区，将应用安装到您的 Slack 工作区。
点击复制以获取 API 令牌，该令牌可验证您的身份并授予您对 API 的访问权限。
将 API 令牌添加到 Secret Manager。
如需查看存储的 Secret，请向项目的 RAG 引擎服务账号授予 Secret Manager Secret Accessor 角色。

以下 curl 和 Python 代码示例演示了如何从您的 Slack 资源导入文件。

curl

如果您想从特定频道获取消息，请更改 CHANNEL_ID。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT/v1beta1/projects/PROJECT_ID/locations/REGION/ragCorpora/RAG_CORPUS_ID/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "slack_source": {
      "channels": [
        {
          "apiKeyConfig": {
            "apiKeySecretVersion": "API_KEY_SECRET_VERSION"
          },
          "channels": [
            {
              "channel_id": "CHANNEL_ID"
            }
          ]
        }
      ]
    }
  }
}'

Python

如果您想获取指定时间范围或特定渠道的消息，请更改以下任一字段：

START_TIME
END_TIME
CHANNEL1 或 CHANNEL2

    # Slack example
    start_time = protobuf.timestamp_pb2.Timestamp()
    start_time.GetCurrentTime()
    end_time = protobuf.timestamp_pb2.Timestamp()
    end_time.GetCurrentTime()
    source = rag.SlackChannelsSource(
        channels = [
            SlackChannel("CHANNEL1", "api_key1"),
            SlackChannel("CHANNEL2", "api_key2", START_TIME, END_TIME)
        ],
    )

    response = rag.import_files(
        corpus_name=(
            "projects/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

从 Jira 导入文件

如需将 Jira 中的文件导入到您的语料库中，请执行以下操作：

创建语料库，这是一种索引，可对您的数据进行结构化和优化，以便进行搜索。如需了解详情，请参阅方法：ragCorpora.create。
如需创建 API 令牌，请登录 Atlassian 网站。
在请求中使用 {YOUR_ORG_ID}.atlassian.net 作为 SERVER_URI。
在请求中使用您的 Atlassian 电子邮件地址作为 EMAIL。
在请求中提供 projects 或 customQueries。如需详细了解自定义查询，请参阅使用 Jira 查询语言 (JQL) 进行高级搜索。

导入 projects 时，projects 会展开为相应的查询，以获取整个项目。例如，MyProject 会展开为 project = MyProject。
点击复制以获取 API 令牌，该令牌可验证您的身份并授予您对 API 的访问权限。
将 API 令牌添加到 Secret Manager。
向项目的 RAG 引擎服务账号授予 Secret Manager Secret Accessor 角色。

curl

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT/v1beta1/projects/PROJECT_ID/locations/REGION/ragCorpora/RAG_CORPUS_ID/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "jiraSource": {
      "jiraQueries": [{
        "projects": ["JIRA_PROJECT"],
        "customQueries": ["CUSTOM_QUERY"],
        "email": "EMAIL",
        "serverUri": "SERVER_URI",
        "apiKeyConfig": {
          "apiKeySecretVersion": "API_KEY_SECRET_VERSION"
        }
      }]
    }
  }
}'

Python

    # Jira Example
    jira_query = rag.JiraQuery(
        email="EMAIL",
        jira_projects=["JIRA_PROJECT"],
        custom_queries=["CUSTOM_QUERY"],
        api_key="API_KEY_SECRET_VERSION",
        server_uri="SERVER_URI"
    )
    source = rag.JiraSource(
        queries=[jira_query],
    )

    response = rag.import_files(
        corpus_name=(
            "projects/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

从 SharePoint 导入文件

如需将 SharePoint 网站中的文件导入到语料库，请执行以下操作：

创建语料库，这是一种索引，可对您的数据进行结构化和优化，以便进行搜索。如需了解详情，请参阅方法：ragCorpora.create。
创建 Azure 应用以访问 SharePoint 网站。
1. 如需创建注册，请前往应用注册。
  1. 为此应用提供名称。
  2. 选择仅此组织目录中的账号选项。
  3. 验证重定向 URI 是否为空。
2. 在概览部分中，使用您的应用（客户端）ID 作为 CLIENT_ID，并使用您的“目录（租户）ID”作为 TENANT_ID。
3. 在管理部分中，执行以下操作来更新 API 权限：
  1. 添加 SharePoint Sites.Read.All 权限。
  2. 添加 Microsoft Graph Files.Read.All 和 Browser SiteLists.Read.All 权限。
  3. 授予管理员同意权，使这些权限更改生效。
4. 在管理部分中，执行以下操作：
  1. 使用新的客户端密钥更新证书和 Secret。
  2. 使用 API_KEY_SECRET_VERSION 将 Secret 值添加到 Secret Manager。
向项目的 RAG 引擎服务账号授予 Secret Manager Secret Accessor 角色。
使用 {YOUR_ORG_ID}.sharepoint.com 作为 SHAREPOINT_SITE_NAME。
必须在请求中指定 SharePoint 网站中的云端硬盘名称或云端硬盘 ID。
可选：可以指定云端硬盘上的文件夹路径或文件夹 ID。如果未指定文件夹路径或文件夹 ID，系统会导入云端硬盘上的所有文件夹和文件。

查找网站 ID

打开浏览器，然后前往目标 SharePoint 网站网址。
将 /_api/site/id/ 附加到该网址的末尾。

示例： https://example-sp.sharepoint.com/sites/example-site/_api/site/id/

网页返回 XML 载荷。请注意 Edm.Guid 后面的字符串。这是您的网站 ID。

查找云端硬盘 ID

使用您收集的网站 ID，通过 Microsoft Graph 浏览器或您的 API 客户端发出经过身份验证的 GET 请求：

GET https://graph.microsoft.com/v1.0/sites/SITE_ID/drive

获取 SHAREPOINT_DRIVE_ID。该值列在 JSON 响应的 id 字段中。

查找特定文件夹 ID

使用您的 Drive ID 列出根目录的子目录：

GET https://graph.microsoft.com/v1.0/drives/SHAREPOINT_DRIVE_ID/root/children

在 JSON 响应中找到与所选文件夹名称匹配的对象，然后复制其对应的 id 字符串。这是您的 SHAREPOINT_FOLDER_ID。

curl

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT/v1beta1/projects/PROJECT_ID/locations/REGION/ragCorpora/RAG_CORPUS_ID/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "sharePointSources": {
      "sharePointSource": [{
        "clientId": "CLIENT_ID",
        "apiKeyConfig": {
          "apiKeySecretVersion": "API_KEY_SECRET_VERSION"
        },
        "tenantId": "SHAREPOINT_TENANT_ID",
        "sharepointSiteName": "SHAREPOINT_SITE_NAME",
        "sharepointFolderId": "SHAREPOINT_FOLDER_ID",
        "driveId": "SHAREPOINT_DRIVE_ID"
      }]
    }
  }
}'

Python

    from vertexai.preview import rag
    from vertexai.preview.rag.utils import resources
    import vertexai

    vertexai.init(
        project="PROJECT_ID",
        location="REGION",
    )

    # SharePoint Example.
    source = resources.SharePointSources(
        share_point_sources=[
            resources.SharePointSource(
                client_id="CLIENT_ID",
                client_secret="API_KEY_SECRET_VERSION",
                tenant_id="SHAREPOINT_TENANT_ID",
                sharepoint_site_name="SHAREPOINT_SITE_NAME",
                sharepoint_folder_id="SHAREPOINT_FOLDER_ID",
                drive_id="SHAREPOINT_DRIVE_ID",
            )
        ]
    )

    response = rag.import_files(
        corpus_name=(
            "projects/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

后续步骤

Gemini Enterprise Agent Platform 上 RAG 引擎中的向量数据库选项