此页面由 Cloud Translation API 翻译。

将数据提取功能与 Vertex AI RAG Engine 搭配使用

本页介绍了如何使用支持的数据源（例如 Cloud Storage、Google 云端硬盘、Slack、Jira 或 SharePoint）执行数据提取，以及如何将这些数据与 Vertex AI RAG 引擎搭配使用。导入 RagFiles API 可为这些数据源提供数据连接器。

RAG 支持的数据源

支持以下数据源：

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

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

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

如需了解详情，请参阅 RAG API 参考文档。

数据去重

如果同一文件多次导入且没有任何更改，系统会跳过该文件，因为它已存在。因此，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 语料库中的说明创建语料库。
如需从 Cloud Storage 或 Google 云端硬盘导入文件，请使用模板。

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

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

从 Slack 导入文件

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

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

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

curl

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

API_KEY_SECRET_VERSION=SLACK_API_KEY_SECRET_VERSION
CHANNEL_ID=SLACK_CHANNEL_ID
PROJECT_ID=us-central1

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/${ PROJECT_ID }/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/my-project/locations/us-central1/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

从 Jira 导入文件

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

创建语料库，这是一种索引，可对您的数据进行结构化和优化，以便进行搜索。按照创建 RAG 语料库中的说明操作。
如需创建 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。
向项目的 Vertex AI RAG 引擎服务账号授予 Secret Manager Secret Accessor 角色。

curl

EMAIL=JIRA_EMAIL
API_KEY_SECRET_VERSION=JIRA_API_KEY_SECRET_VERSION
SERVER_URI=JIRA_SERVER_URI
CUSTOM_QUERY=JIRA_CUSTOM_QUERY
PROJECT_ID=JIRA_PROJECT
REGION= "us-central1"

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": ["'"${ PROJECT_ID }"'"],
        "customQueries": ["'"${ CUSTOM_QUERY }"'"],
        "email": "'"${ EMAIL }"'",
        "serverUri": "'"${ SERVER_URI }"'",
        "apiKeyConfig": {
          "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
        }
      }]
    }
  }
}'

Python

    # Jira Example
    jira_query = rag.JiraQuery(
        email="xxx@yyy.com",
        jira_projects=["project1", "project2"],
        custom_queries=["query1", "query2"],
        api_key="api_key",
        server_uri="server.atlassian.net"
    )
    source = rag.JiraSource(
        queries=[jira_query],
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/REGION/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

从 SharePoint 导入文件

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

创建语料库，这是一种索引，可对您的数据进行结构化和优化，以便进行搜索。按照创建 RAG 语料库中的说明操作。
创建 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。
向项目的 Vertex AI RAG 引擎服务账号授予 Secret Manager Secret Accessor 角色。
使用 {YOUR_ORG_ID}.sharepoint.com 作为 SHAREPOINT_SITE_NAME。
请求中必须指定 SharePoint 网站中的云端硬盘名称或云端硬盘 ID。
可选：可以指定驱动器上的文件夹路径或文件夹 ID。如果未指定文件夹路径或文件夹 ID，系统会导入云端硬盘上的所有文件夹和文件。

curl

CLIENT_ID=SHAREPOINT_CLIENT_ID
API_KEY_SECRET_VERSION=SHAREPOINT_API_KEY_SECRET_VERSION
TENANT_ID=SHAREPOINT_TENANT_ID
SITE_NAME=SHAREPOINT_SITE_NAME
FOLDER_PATH=SHAREPOINT_FOLDER_PATH
DRIVE_NAME=SHAREPOINT_DRIVE_NAME

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": "'"${ TENANT_ID }"'",
        "sharepointSiteName": "'"${ SITE_NAME }"'",
        "sharepointFolderPath": "'"${ FOLDER_PATH }"'",
        "driveName": "'"${ DRIVE_NAME }"'"
      }]
    }
  }
}'

Python

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

    CLIENT_ID="SHAREPOINT_CLIENT_ID"
    API_KEY_SECRET_VERSION="SHAREPOINT_API_KEY_SECRET_VERSION"
    TENANT_ID="SHAREPOINT_TENANT_ID"
    SITE_NAME="SHAREPOINT_SITE_NAME"
    FOLDER_PATH="SHAREPOINT_FOLDER_PATH"
    DRIVE_NAME="SHAREPOINT_DRIVE_NAME"

    # SharePoint Example.
    source = resources.SharePointSources(
        share_point_sources=[
            resources.SharePointSource(
                client_id=CLIENT_ID,
                client_secret=API_KEY_SECRET_VERSION,
                tenant_id=TENANT_ID,
                sharepoint_site_name=SITE_NAME,
                folder_path=FOLDER_PATH,
                drive_id=DRIVE_ID,
            )
        ]
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/REGION/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

后续步骤

Vertex AI RAG 引擎中的向量数据库选项

将数据提取功能与 Vertex AI RAG Engine 搭配使用 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

RAG 支持的数据源

数据去重

了解导入失败

响应元数据

导入结果接收器

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

从 Slack 导入文件

curl

Python

从 Jira 导入文件

curl

Python

从 SharePoint 导入文件

curl

Python

后续步骤

将数据提取功能与 Vertex AI RAG Engine 搭配使用