File Search Stores

File Search API 提供托管的问答服务，用于使用 Google 的基础架构构建检索增强生成 (RAG) 系统。

REST 资源：fileSearchStores

资源：FileSearchStore

FileSearchStore 是 Document 的集合。

字段
name string

仅限输出。不可变。标识符。FileSearchStore 资源名称。这是一个 ID（不含“fileSearchStores/”前缀的名称），最多可包含 40 个字符，这些字符可以是小写字母数字字符或短划线 (-)。此属性仅供输出。唯一名称将从 displayName 派生，并附带一个 12 字符的随机后缀。示例：fileSearchStores/my-awesome-file-search-store-123a456b789c 如果未提供 displayName，系统会随机生成名称。

displayName string

可选。FileSearchStore 的人类可读显示名称。显示名称的长度不得超过 512 个字符（包括空格）。示例：“语义检索器上的文档”

createTime string (Timestamp format)

仅限输出。创建 FileSearchStore 时的时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

updateTime string (Timestamp format)

仅限输出。上次更新 FileSearchStore 时的时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

activeDocumentsCount string (int64 format)

仅限输出。FileSearchStore 中处于有效状态且可供检索的文档数量。

pendingDocumentsCount string (int64 format)

仅限输出。正在处理的 FileSearchStore 中的文档数量。

failedDocumentsCount string (int64 format)

仅限输出。FileSearchStore 中处理失败的文档数量。

sizeBytes string (int64 format)

仅限输出。提取到 FileSearchStore 中的原始字节的大小。这是 FileSearchStore 中所有文档的总大小。

embeddingModel string

可选。要为 FileSearchStore 使用的嵌入模型。模型的资源名称。用作模型使用的 ID。格式：models/{model}。如果未指定，系统将使用默认的嵌入模型。

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string,
  "activeDocumentsCount": string,
  "pendingDocumentsCount": string,
  "failedDocumentsCount": string,
  "sizeBytes": string,
  "embeddingModel": string
}

方法：fileSearchStores.create

创建空的 FileSearchStore。

端点

post https://generativelanguage.googleapis.com/v1beta/fileSearchStores

请求正文

请求正文包含一个 FileSearchStore 实例。

字段
displayName string

可选。FileSearchStore 的人类可读显示名称。显示名称的长度不得超过 512 个字符（包括空格）。示例：“语义检索器上的文档”

embeddingModel string

可选。要为 FileSearchStore 使用的嵌入模型。模型的资源名称。用作模型使用的 ID。格式：models/{model}。如果未指定，系统将使用默认的嵌入模型。

响应正文

如果成功，响应正文将包含一个新创建的 FileSearchStore 实例。

方法：fileSearchStores.delete

删除 FileSearchStore。

端点

delete https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*}

路径参数

name string

必需。FileSearchStore 的资源名称。示例：fileSearchStores/my-file-search-store-123 格式为 fileSearchStores/{filesearchstore}。

查询参数

force boolean

可选。如果设置为 true，则与此 FileSearchStore 相关的所有 Document 和对象也会被删除。

如果为 false（默认值），则当 FileSearchStore 包含任何 Document 时，系统会返回 FAILED_PRECONDITION 错误。

请求正文

请求正文必须为空。

响应正文

如果成功，则响应正文为空的 JSON 对象。

方法：fileSearchStores.get

获取有关特定 FileSearchStore 的信息。

端点

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*}

路径参数

name string

必需。FileSearchStore 的名称。示例：fileSearchStores/my-file-search-store-123 格式为 fileSearchStores/{filesearchstore}。

请求正文

请求正文必须为空。

响应正文

如果成功，则响应正文包含一个 FileSearchStore 实例。

方法：fileSearchStores.list

列出用户拥有的所有 FileSearchStores。

端点

get https://generativelanguage.googleapis.com/v1beta/fileSearchStores

查询参数

pageSize integer

可选。要返回的 FileSearchStores 的数量上限（每页）。服务返回的数量可能少于 FileSearchStores。

如果未指定，则最多返回 10 个 FileSearchStores。每页的上限为 20 FileSearchStores。

pageToken string

可选。从之前的 fileSearchStores.list 调用中收到的页面令牌。

在下一个请求中提供响应中返回的 nextPageToken 作为实参，以检索下一页。

进行分页时，提供给 fileSearchStores.list 的所有其他参数必须与提供页面令牌的调用匹配。

请求正文

请求正文必须为空。

响应正文

来自 fileSearchStores.list 的响应，包含分页的 FileSearchStores 列表。结果按 fileSearchStore.create_time 升序排序。

如果成功，响应正文将包含结构如下的数据：

字段
fileSearchStores[] object (FileSearchStore)

返回的 rag_stores。

nextPageToken string

可作为 pageToken 发送并用于检索下一页的令牌。如果省略此字段，则没有更多页面。

JSON 表示法 
{
  "fileSearchStores": [
    {
      object (FileSearchStore)
    }
  ],
  "nextPageToken": string
}

方法：fileSearchStores.importFile

将 File 从文件服务导入到 FileSearchStore。

端点

post https://generativelanguage.googleapis.com/v1beta/{fileSearchStoreName=fileSearchStores/*}:importFile

路径参数

fileSearchStoreName string

必需。不可变。要将文件导入到的 FileSearchStore 的名称。示例：fileSearchStores/my-file-search-store-123 格式为 fileSearchStores/{filesearchstore}。

请求正文

请求正文中包含结构如下的数据：

字段
fileName string

必需。要导入的 File 的名称。示例：files/abc-123

customMetadata[] object (CustomMetadata)

要与文件关联的自定义元数据。

chunkingConfig object (ChunkingConfig)

可选。用于告知服务如何将文件分块的配置。如果未提供，服务将使用默认参数。

响应正文

如果成功，则响应正文包含一个 Operation 实例。

REST 资源：fileSearchStores.operations

资源：Operation

此资源表示由网络 API 调用引发的长时间运行的操作。

字段
name string

由服务器分配的名称，该名称仅在最初返回它的那项服务中是唯一的。如果您使用默认 HTTP 映射，则 name 应是以 operations/{unique_id} 结尾的资源名称。

metadata object

与操作关联的服务专属元数据。它通常包含进度信息和常见元数据（如创建时间）。一些服务可能不会提供此类元数据。任何返回长时间运行的操作的方法都应记录元数据类型（如果有的话）。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

done boolean

如果值为 false，则表示操作仍在进行中。如果为 true，则表示操作已完成，其结果不是 error 就是 response。

result Union type
操作结果，可以是 error，也可以是有效的 response。如果 done == false，则既不会设置 error，也不会设置 response。如果 done == true，则只能设置 error 或 response 中的一项。部分服务可能不会提供结果。result 只能是下列其中一项：
error object (Status)

操作失败或被取消时表示有错误发生的结果。

response object

操作的常规成功响应。如果原始方法在成功时不返回任何数据（如 Delete），则响应为 google.protobuf.Empty。如果原始方法为标准 Get/Create/Update 方法，则响应应该为资源。对于其他方法，响应类型应为 XxxResponse，其中 Xxx 是原始方法的名称。例如，如果原始方法名称为 TakeSnapshot()，则推断的响应类型为 TakeSnapshotResponse。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

JSON 表示法 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

方法：fileSearchStores.operations.get

获取长时间运行的操作的最新状态。客户端可以使用此方法，按 API 服务建议的时间间隔来轮询操作结果。

端点

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/operations/*}

路径参数

name string

操作资源的名称。 格式为 fileSearchStores/{filesearchstore}/operations/{operation}。

请求正文

请求正文必须为空。

响应正文

如果成功，则响应正文包含一个 Operation 实例。

REST 资源：fileSearchStores.upload.operations

资源：Operation

此资源表示由网络 API 调用引发的长时间运行的操作。

字段
name string

由服务器分配的名称，该名称仅在最初返回它的那项服务中是唯一的。如果您使用默认 HTTP 映射，则 name 应是以 operations/{unique_id} 结尾的资源名称。

metadata object

与操作关联的服务专属元数据。它通常包含进度信息和常见元数据（如创建时间）。一些服务可能不会提供此类元数据。任何返回长时间运行的操作的方法都应记录元数据类型（如果有的话）。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

done boolean

如果值为 false，则表示操作仍在进行中。如果为 true，则表示操作已完成，其结果不是 error 就是 response。

result Union type
操作结果，可以是 error，也可以是有效的 response。如果 done == false，则既不会设置 error，也不会设置 response。如果 done == true，则只能设置 error 或 response 中的一项。部分服务可能不会提供结果。result 只能是下列其中一项：
error object (Status)

操作失败或被取消时表示有错误发生的结果。

response object

操作的常规成功响应。如果原始方法在成功时不返回任何数据（如 Delete），则响应为 google.protobuf.Empty。如果原始方法为标准 Get/Create/Update 方法，则响应应该为资源。对于其他方法，响应类型应为 XxxResponse，其中 Xxx 是原始方法的名称。例如，如果原始方法名称为 TakeSnapshot()，则推断的响应类型为 TakeSnapshotResponse。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

JSON 表示法 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

方法：fileSearchStores.upload.operations.get

获取长时间运行的操作的最新状态。客户端可以使用此方法，按 API 服务建议的时间间隔来轮询操作结果。

端点

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/upload/operations/*}

路径参数

name string

操作资源的名称。 格式为 fileSearchStores/{filesearchstore}/upload/operations/{operation}。

请求正文

请求正文必须为空。

响应正文

如果成功，则响应正文包含一个 Operation 实例。

方法：media.uploadToFileSearchStore

将数据上传到 FileSearchStore，在存储到 FileSearchStore 文档之前对其进行预处理和分块。

端点

  • 上传 URI，用于媒体上传请求：
 post https://generativelanguage.googleapis.com/upload/v1beta/{fileSearchStoreName=fileSearchStores/*}:uploadToFileSearchStore
  • 元数据 URI，用于仅涉及元数据的请求：
 post https://generativelanguage.googleapis.com/v1beta/{fileSearchStoreName=fileSearchStores/*}:uploadToFileSearchStore

路径参数

fileSearchStoreName string

必需。不可变。要将文件上传到的 FileSearchStore 的名称。示例：fileSearchStores/my-file-search-store-123 格式为 fileSearchStores/{filesearchstore}。

请求正文

请求正文中包含结构如下的数据：

字段
displayName string

可选。所创建文档的显示名称。

customMetadata[] object (CustomMetadata)

要与数据相关联的自定义元数据。

chunkingConfig object (ChunkingConfig)

可选。用于告知服务如何对数据进行分块的配置。如果未提供，服务将使用默认参数。

mimeType string

可选。数据的 MIME 类型。如果未提供，系统会根据上传的内容进行推断。

响应正文

如果成功，响应正文将包含结构如下的数据：

字段
name string

由服务器分配的名称，该名称仅在最初返回它的那项服务中是唯一的。如果您使用默认 HTTP 映射，则 name 应是以 operations/{unique_id} 结尾的资源名称。

metadata object

与操作关联的服务专属元数据。它通常包含进度信息和常见元数据（如创建时间）。一些服务可能不会提供此类元数据。任何返回长时间运行的操作的方法都应记录元数据类型（如果有的话）。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

done boolean

如果值为 false，则表示操作仍在进行中。如果为 true，则表示操作已完成，其结果不是 error 就是 response。

result Union type
操作结果，可以是 error，也可以是有效的 response。如果 done == false，则既不会设置 error，也不会设置 response。如果 done == true，则只能设置 error 或 response 中的一项。部分服务可能不会提供结果。result 只能是下列其中一项：
error object (Status)

操作失败或被取消时表示有错误发生的结果。

response object

操作的常规成功响应。如果原始方法在成功时不返回任何数据（如 Delete），则响应为 google.protobuf.Empty。如果原始方法为标准 Get/Create/Update 方法，则响应应该为资源。对于其他方法，响应类型应为 XxxResponse，其中 Xxx 是原始方法的名称。例如，如果原始方法名称为 TakeSnapshot()，则推断的响应类型为 TakeSnapshotResponse。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标示相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

JSON 表示法 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}