文档数据
您可以通过 Web 控制台或 RESTful API 创建、运行和管理 Pipelines。Web 控制台操作更简单直观，但 RESTful API 可提供更多灵活性。
本文将介绍如何创建文档 Pipeline、进行语义搜索并删除 Pipeline。
前提条件与限制
-
请确保您创建部署在阿里云（杭州）的集群。
-
同一项目下，您可最多创建 100 个同一类型的 Pipelines。更多详情，请参考使用限制。
摄取文档数据
摄取文档数据包含两个步骤：创建 Ingestion Pipeline 和运行 Ingestion Pipeline。
创建文档 Ingestion Pipeline
- Cloud Console
- cURL
-
打开项目。
-
点击左侧导航栏中的 Pipelines。 选中概览标签页，并切换到 Pipelines。点击 + Pipeline。
-
选择需要创建的 Pipeline 类 型。点击 Ingestion Pipeline 一栏中的 + Pipeline 按钮。
-
配置 Ingestion Pipeline。
参数
说明
目标集群
自动创建 Collection 所属的集群。目前仅支持部署在阿里云（杭州）的集群。
Collection 名称
自动创建的 Collection 的名称。
Pipeline 名称
新创建的 Ingestion Pipeline 的名称。名称中只可包含小写字母、数字和下划线。
描述 (可选)
对新创建的 Ingestion Pipeline 的描述。
-
添加 Function。1 个 Ingestion pipeline 中只可添加 1 个 INDEX Function。
-
输入 Function 名称。
-
选择 INDEX_DOC Function。将对象存储（OSS）预签名 URL 中或本地上传的文档切分为文档块，并转换为 Embedding 向量。
-
选择用于生成向量的 Embedding 模型。根据所选的文档语言，您可以选择不同的 Embedding 模型。目前 Zilliz Cloud Pipelines 共提供两种 Embedding 模型：英语——zilliz/bge-base-en-v1.5，中文——zilliz/bge-base-zh-v1.5。
Embedding 模型
说明
zilliz/bge-base-en-v1.5
智源研究院（BAAI）发布的开源 Embedding 向量模型。该模型与 向量数据库共同托管于 Zilliz Cloud 上，具备出色的性能，可大幅降低延时。
zilliz/bge-base-zh-v1.5
智源研究院（BAAI）发布的开源 Embedding 向量模型。该模型与向量数据库共同托管于 Zilliz Cloud 上，具备出色的性能，可大幅降低延时。
-
点击添加。
-
-
(可选) 添加 PRESERVE Function。PRESERVE Function 在 Collection 中添加标量字段，用于保留文档元数据。
📘说明每个 Ingestion Pipeline 中最多可添加 50 个 PRESERVE Function。
-
点击 + Function。
-
输入 Function 名称。
-
配置输入字段名称和数据类型。支持的数据字段类型包括 Bool、Int8、Int16、Int32、Int64、Float、Double 和 VarChar。
📘说明目前，输出字段名称必须与输入字段名称保持一致。在运行 Ingestion Pipeline 时，您将使用到输入字段名称。而输出字段名称用于自动生成的 Collection Schema 中作为保留的标量字段名称。
字段类型为 VarChar 时，字符串最大长度为 4,000 个字符，且只可包含数字、字母。
在标量字段中存储日期时，我们推荐使用 Int16 的数据 类型。存储时间时，我们推荐使用 Int32 的数据类型。
-
点击添加。
-
-
点击创建 Ingestion Pipeline。
-
继续创建 Search pipeline 和 Deletion pipeline。创建的 Search 和 Deletion Pipeline 可适应配套刚才创建的Ingestion Pipeline。
📘说明自动创建的 Search Pipeline 默认关闭 Reranker 功能，如需使用 Reranker，请手动创建一个新的 Search Pipeline。
以下示例代码创建了 1 个名称为 my_doc_ingestion_pipeline 的 Ingestion Pipeline，并添加了 1 个 INDEX_DOC Function 和 1 个 PRESERVE Function。
curl --request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines" \
-d '{
"projectId": "proj-xxxx"，
"name": "my_doc_ingestion_pipeline",
"description": "A pipeline that splits a doc file into chunks and generates embeddings. It also stores the publish_year with each chunk.",
"type": "INGESTION",
"functions": [
{
"name": "index_my_doc",
"action": "INDEX_DOC",
"language": "ENGLISH",
"chunkSize": 500,
"embedding": "zilliz/bge-base-en-v1.5",
"splitBy": ["\n\n", "\n", " ", ""]
},
{
"name": "keep_doc_info",
"action": "PRESERVE",
"inputField": "publish_year",
"outputField": "publish_year",
"fieldType": "Int16"
}
],
"clusterId": "inxx-xxxxxxxxxxxxxxx",
"collectionName": "my_collection"
}'
以下为参数说明：
-
YOUR_API_KEY: 验证 API 请求的鉴权信息。了解如何查看 API 密钥。 -
cloud-region: 集群所在云服务地域的 ID。目前仅支持ali-cn-hangzhou。 -
clusterId: 创建 Pipeline 所属的集群 ID。目前，仅支持部署在阿里云（杭州）的集群。了解如何获取集群 ID。 -
projectId: 创建 Pipeline 所属的项目 ID。了解如何获取项目 ID。 -
collectionName: 与 Pipeline 同步自动创建的 Collection 名称。或者，您也可以指定一个已有的 Collection。 -
name: 创建的 Pipeline 名称。Pipeline 名称应该在 3-64 个字符内，且只可包含数字、字母和下划线。 -
description(可选): 创建的 Pipeline 描述。 -
type: 创建的 Pipeline 类型。目前，可创建的 Pipeline 类型包括INGESTION、SEARCH和DELETION。 -
functions: Pipeline 中添加的 Function。1 个 Ingestion pipeline 中只可添加 1 个 INDEX Function 和至多 50 个 PRESERVE Function。-
name: Function 名称。Function 名称应该在 3-64 个字符内，且只可包含数字、字母和下划线。 -
action: Function 类型。您可以在 Ingestion Pipeline 中添加的 Function 类型包括：INDEX_DOC、INDEX_TEXT、INDEX_IMAGE和PRESERVE。 -
language: 文档语言。可选择的语言包括ENGLISH（英语） 和CHINESE（中文）。(仅INDEX_DOC和INDEX_TEXTFunction 中包含此参数。） -
embedding: 用于生成向量的 Embedding 模型。 (仅INDEXFunction 中包含此参数。）Embedding 模型
说明
zilliz/bge-base-en-v1.5
智源研究院（BAAI）发布的开源 Embedding 向量模型。该模型与向量数据库共同托管于 Zilliz Cloud 上，具备出色的性能，可大幅降低延时。
zilliz/bge-base-zh-v1.5
智源研究院（BAAI）发布的开源 Embedding 向量模型。该模型与向量数据库共同托管于 Zilliz Cloud 上，具备出色的性能，可大幅降低延时。
-
splitBy(可选): Splitter 用于分割文本。选择或自定义 Splitter 后，Ingestion Pipeline 会根据定义的字符按顺序将文本分割成小片段。默认情况下，Zilliz Cloud Pipeline 使用"\n\n", "\n", " ", ""作为分隔符。(仅INDEX_DOCFunction 中包含此参数。） -
chunkSize(可选):INDEX_DOCFunction 将每个文档分割成更小的切片。默认情况下，每个切片包含不超过500 个 Token，但您可以根据自己的切片策略调整切片大小。此外，对于 Markdown 或 HTML 文件，该Function 会首先按标题划分文档，然后根据指定的切片大小进一步按较大的部分划分。(仅INDEX_DOCFunction 中包含此参数。）下表罗列了 Embedding 模型与其可选切片大小范围 。
模型
切片大小范围 (Tokens)
zilliz/bge-base-en-v1.5
20-500 Tokens
zilliz/bge-base-zh-v1.5
20-500 Tokens
-
-
inputField: 输入字段名称。 您可以自定义输入字段名称，但需要与outputField保持一致。（仅PRESERVEFunction 中包含此参数。） -
outputField: 输出字段名称。该字段将的值将用于构成 Collection Schema。outputField字段值应该与inputField字段值保持一致。 (仅PRESERVEFunction 中包含此参数。） -
fieldType: 输入和输出字段的字段类型。可选的值包括：Bool、Int8、Int16、Int32、Int64、Float、Double和VarChar。 (仅PRESERVEFunction 中包含此参数。）📘说明在标量字段中存储日期时，我们推荐使用 Int16 的数据类型。存储时间时，我们推荐使用 Int32 的数据类型。
对于
VarChar字段类型而言，字段数据的最大长度max_length不得超过 4,000。
如果请求返回以下类似内容，则表示 Ingestion Pipeline 创建成功：
{
"code": 200,
"data": {
"pipelineId": "pipe-xxxx",
"name": "my_doc_ingestion_pipeline",
"type": "INGESTION",
"createTimestamp": 1721187300000,
"description": "A pipeline that splits a doc file into chunks and generates embeddings. It also stores the publish_year with each chunk.",
"status": "SERVING",
"totalUsage": {
"embedding": 0
},
"functions": [
{
"action": "INDEX_DOC",
"name": "index_my_doc",
"inputField": "doc_url",
"language": "ENGLISH",
"chunkSize": 500,
"embedding": "zilliz/bge-base-en-v1.5"，
"splitBy": ["\n\n", "\n", " ", ""]
},
{
"action": "PRESERVE",
"name": "keep_doc_info",
"inputField": "publish_year",
"outputField": "publish_year",
"fieldType": "Int16"
}
],
"clusterId": "in03-***************",
"collectionName": "my_collection"
}
}
总用量 totalUsage非实时更新，数据统计可能会有几小时延迟。
Ingestion Pipeline 创建成功后，Zilliz Cloud 将进行重名检查。如果集群中没有该名称的 Collection，将自动创建名称为 my_collection 的新 Collection。如果已存在同名的 Collection，Zilliz Cloud Pipelines 会继续检查该已有 Collection 的 Schema 是否与 Pipeline 中定义的一致。
该 Collection 中包含 6 个字段：1 个自动生成的 ID 字段、4 个 INDEX_DOC function 的输出字段和 1 个 PRESERVE function 的输出字段。Collection Schema 如下所示：
id | doc_name | chunk_id | chunk_text | embedding | publish_year |
|---|
运行文档 Ingestion Pipeline
- Cloud Console
- cURL
-
点击 Ingestion Pipeline 右侧的 "▶︎" 按钮。 或者您可以点击 Playground 选项卡。
-
摄取文件。Zilliz Cloud 提供两种摄取数据的方式。
-
导入对象存储中的文件。在
doc_url字段中输入阿里云签名 URL。 -
上传本地文件。点击添加附件。 在对话框中上传本地文件。文件大小不得超过 10 MB。支持文档文件类型包括
.txt、.pdf、.md、.html、.epub、.csv、.doc、.docx、.xls、.xlsx、.ppt、.pptx。如 Ingestion Pipeline 中添加了 PRESERVE function，您还需要额外配置data字段。
-
-
查看运行结果。
您可以选择在运行 Ingestion Pipelines 时通过对象存储服务上传文件或直接上传本地文件。
通过对象存储服务上传文件
-
在运行前，先将文档上传至对象存储服务（例如：阿里云对象存储）。支持文档文件类型包括
.txt、.pdf、.md、.html、.epub、.csv、.doc、.docx、.xls、.xlsx、.ppt、.pptx。 -
文档成功上传至 OSS 后，获取预签名 URL。
-
以下示例代码用于运行 Ingestion pipeline
my_doc_ingestion_pipeline。publish_year是需要保留的元数据字段。curl --request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines/${YOUR_PIPELINE_ID}/run" \
-d '{
"data": {
"doc_url": "https://storage.googleapis.com/example-bucket/zilliz_concept_doc.md?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T181309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f169edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa8496def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dcc1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c20580e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b133447032ea7abedc098d2eb14a7",
"publish_year": 2023
}
}'以下为参数说明：
-
YOUR_API_KEY: 验证 API 请求的鉴权信息。了解如何查看 API 密钥。 -
cloud-region: 集群的云服务地域。目前仅支持ali-cn-hangzhou。 -
YOUR_PIPELINE_ID：需要运行的 Pipeline 的 ID。 -
doc_url: 对象存储中的文档 URL。文档 URL 包含中文时，请勿使用编码后的 URL。您可以使用 UTF-8 编码的 URL。请确保 URL 有效期大于 1 小时。 -
元数据字段 (可选): 需要保留的元数据字段。输入字段名称必须与创建时的配置保持一致。
请求返回以下类似内容：
{
"code": 200,
"data": {
"doc_name": "zilliz_concept_doc.md",
"usage": {
"embedding": 1241
},
"num_chunks": 3
}📘说明输出的
doc_name字段十分重要。如果内容相同的文档被赋予了不同的doc_name，且运行了两次 Ingestion pipeline，那么同样的文档内容将在向量数据库中存储两遍。 -
上传本地文件
通过以下示例直接上传本 地文件。
curl --request POST \
--header "Content-Type: multipart/form-data" \
--header 'Accept: multipart/form-data' \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines/${YOUR_PIPELINE_ID}/run_ingestion_with_file" \
--form 'data={"year": 2023}' \
--form 'file=@path/to/local/file.ext'
以下为参数说明：
-
YOUR_API_KEY: 验证 API 请求的鉴权信息。了解如何查看 API 密钥。 -
cloud-region: 集群的云服务地域。目前仅支持ali-cn-hangzhou。 -
YOUR_PIPELINE_ID：需要运行的 Pipeline 的 ID。 -
file: 本地文件路径。支持文档文件类型包括.txt、.pdf、.md、.html、.epub、.csv、.doc、.docx、.xls、.xlsx、.ppt、.pptx。 -
data(可选): 需要保留的元数据字段。输入字段名称必须与创建时的配置保持一致。
请求返回以下类似内容：
{
"code": 200,
"data": {
"doc_name": "zilliz_concept_doc.md",
"usage": {
"embedding": 1241
},
"num_chunks": 3
}
搜索文档数据
搜索数据前，请先创建并运行 Search Pipeline。与 Ingestion 和 Deletion Pipelines 不同，Search Pipeline 创建时是在 Function 级别定义集群和 Collection，而非在 Pipeline 层级。这是因为 Zilliz Cloud 支持同时从多个 Collection 搜索数据。
创建文档 Search Pipeline
- Cloud Console
- cURL
-
打开项目。
-
点击左侧导航栏中的 Pipelines。 选中概览标签页，并切换到 Pipelines。点击 + Pipeline。
-
选择需要创建的 Pipeline 类型。点击 Search Pipeline 一栏中的 + Pipeline 按钮。
-
配置 Search Pipeline。
参数
说明
Pipeline 名称
新创建的 Ingestion Pipeline 的名称。名称中只可包含小写字母、数字和下划线。
描述 (可选)
对新创建的 Ingestion Pipeline 的描述。
-
点击 + Function 添加 Function。 1 个 Search pipeline 中只可添加 1 个 Function。
-
输入函数名称。
-
选择目标集群和目标 Collection。目标集群必须为部署在阿里云（杭州）的活跃集群。目标 Collection 必须为创建 Ingestion pipeline 时自动创建的 Collection，否则创建的 Search Pipeline 将不兼容。
-
Function 类型选择 SEARCH_DOC。SEARCH_DOC Function 可以将对象存储（OSS）预签名 URL 中或本地上传的文档切分为文档块，并转换为 Embedding 向量。
-
（可选） 如需对输出结果根据相关性进行重新排序、提高搜索结果质量，请开启 Reranker。请注意，开启 Reranker 会增加使用成本和搜索延时。默认情况下，Reranker 功能关闭。开启后，您可以选择 Reranker 模型。目前仅支持 zilliz/bge-reranker-base 模型。
Reranker 模型
描述
zilliz/bge-reranker-base
智源研究院（BAAI）发布的开源重新排序（Reranker）模型。该模型采用交叉编码器架构，并托管于 Zilliz Cloud 上。
-
点击添加。
-
-
点击创建 Search Pipeline。
以下示例代码创建了 1 个名称为 my_text_search_pipeline 的 Search Pipeline，并添加了 1 个 SEARCH_DOC_CHUNK Function。
curl --request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines" \
-d '{
"projectId": "proj-xxxx",
"name": "my_text_search_pipeline",
"description": "A pipeline that receives text and search for semantically similar doc chunks",
"type": "SEARCH",
"functions": [
{
"name": "search_chunk_text_and_title",
"action": "SEARCH_DOC_CHUNK",
"clusterId": "inxx-xxxxxxxxxxxxxxx",
"collectionName": "my_collection",
"embedding": "zilliz/bge-base-en-v1.5",
"reranker": "zilliz/bge-reranker-base"
}
]
}'
以下为参数说明：
-
YOUR_API_KEY: 验证 API 请求的鉴权信息。了解如何查看 API 密钥。 -
cloud-region: 集群所在云服务地域的 ID。目前仅支持ali-cn-hangzhou。 -
projectId: 创建 Pipeline 所属的项目 ID。了解如何获取项目 ID。 -
name: 创建的 Pipeline 名称。Pipeline 名称应该在 3-64 个字符内，且只可包含数字、字母和下划线。 -
description（可选）：创建的 Pipeline 描述。 -
type: 创建的 Pipeline 类型。目前，可创建的 Pipeline 类型包括INGESTION、SEARCH和DELETION。 -
functions: Pipeline 中添加的 Function。1 个 Search Pipeline 中仅可添加 1 个 Function。-
name: Function 名称。Function 名称应该在 3-64 个字符内，且只可包含数字、字母和下划线。 -
action: Function 类型。支持的类型包括：SEARCH_DOC_CHUNK、SEARCH_TEXT、SEARCH_IMAGE_BY_IMAGE、SEARCH_IMAGE_BY_TEXT。 -
inputField: 输入字段名称。您可以自由配置该字段的值。但是在运行 Pipeline 时，您需要使用现在定义的输入字段名称。 -
clusterId: 创建 Pipeline 所属的集群 ID。目前，仅支持部署在阿里云（杭州）的集群。了解如何获取集群 ID。 -
collectionName: 创建 Pipeline 所属的 Collection 名称。 -
reranker（可选）: 使用 Reranker 对输出结果进行重新排序，提高搜索结果质量。目前，仅支持zilliz/bge-reranker-base作为 Reranker 模型。
-
如果请求返回以下类似内容，则表示 Search Pipeline 创建成功：
{
"code": 200,
"data": {
"pipelineId": "pipe-84e6d9dba930e035150972",
"name": "my_text_search_pipeline",
"type": "SEARCH",
"createTimestamp": 1721187655000,
"description": "A pipeline that receives text and search for semantically similar doc chunks",
"status": "SERVING",
"totalUsage": {
"embedding": 0,
"rerank": 0
},
"functions":
{
"action": "SEARCH_DOC_CHUNK",
"name": "search_chunk_text_and_title",
"inputField": "query_text",
"clusterId": "in03-***************",
"collectionName": "my_collection",
"embedding": "zilliz/bge-base-en-v1.5",
"reranker": "zilliz/bge-reranker-base"
}
}
}
总用量 totalUsage 非实时更新，数据统计可能会有几小时延迟
运行文档 Search Pipeline
- Cloud Console
- cURL
-
点击 Search Pipeline 右侧的 "▶︎" 按钮。 或者您可以点击 Playground 选项卡。
-
输入查询文本。点击运行。
-
查看运行结果。
以下示例代码用于运行 Search pipeline my_text_search_pipeline。查询文本为“How many collections can a cluster with more than 8 CUs hold?”（1 个 8 CU 以上的集群最多可创建多少个 Collection）。
curl --request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines/${YOUR_PIPELINE_ID}/run" \
-d '{
"data": {
"query_text": "How many collections can a cluster with more than 8 CUs hold?"
},
"params":{
"limit": 1,
"offset": 0,
"outputFields": [ "chunk_id", "doc_name" ],
"filter": "id >= 0",
}
}'
以下为参数说明：
-
YOUR_API_KEY: 验证 API 请求的鉴权信息。了解如何查看 API 密钥。 -
cloud-region: 集群的云服务地域。目前仅支持ali-cn-hangzhou。 -
query_text: 语义搜索的查询文本。 -
params: 搜索相关参数。-
limit: 返回的 Entity 数量。该参数值为 1-500 之间的整数。limit和offset参数值总和应小于 1024。 -
offset: 在搜索结果中跳过的 Entity 数量。最大值为 1024。limit和offset参数值总和应小于 1024。 -
outputFields: 在搜索结果中一同返回的输出字段。id、distance和chunk_text为默认输出字段。 -
filter: 搜索时的过滤条件。
-
请求返回以下类似内容：
{
"code": 200,
"data": {
"result": [
{
"id": 450524927755105957,
"distance": 0.99967360496521,
"chunk_id": 0,
"doc_name": "zilliz_concept_doc.md",
"chunk_text": "# Cluster, Collection & Entities\nA Zilliz Cloud cluster is a managed Milvus instance associated with certain computing resources. You can create collections in the cluster and insert entities into them. In comparison to a relational database, a collection in a cluster is similar to a table in the database, and an entity in a collection is similar to a record in the table.\\n\\n# Cluster, Collection & Entities\n## Cluster\nWhen creating a cluster on Zilliz Cloud, you must specify the type of CU associated with the cluster. There are three types of CUs available: performance-optimized, capacity-optimized, and cost-optimized. You can learn how to choose among these types in [Select the Right CU](https://zilliverse.feishu.cn/wiki/UgqvwKh2QiKE1kkYNLJcaHt0nkg). \nAfter determining the CU type, you must also specify its size. Note that the number of collections a cluster can hold varies based on its CU size. A cluster with less than 8 CUs can hold no more than 32 collections, while a cluster with more than 8 CUs can hold as many as 256 collections. \nAll collections in a cluster share the CUs associated with the cluster. To save CUs, you can unload some collections. When a collection is unloaded, its data is moved to disk storage and its CUs are freed up for use by other collections. You can load the collection back into memory when you need to query it. Keep in mind that loading a collection requires some time, so you should only do so when necessary.\\n\\n# Cluster, Collection & Entities\n## Collection\nA collection collects data in a two-dimensional table with a fixed number of columns and a variable number of rows. In the table, each column corresponds to a field, and each row represents an entity. \nThe following figure shows a sample collection that comprises six entities and eight fields."
},
{
"id": 450524927755105959,
"distance": 0.07810573279857635,
"chunk_id": 2,
"doc_name": "zilliz_concept_doc.md",
"chunk_text": "# Cluster, Collection & Entities\n## Collection\n### Index\nUnlike Milvus instances, Zilliz Cloud clusters only support the **AUTOINDEX** algorithm for indexing. This algorithm is optimized for the three types of computing units (CUs) supported by Zilliz Cloud. For more information, see [AUTOINDEX Explained](https://zilliverse.feishu.cn/wiki/EA2twSf5oiERMDkriKScU9GInc4).\\n\\n# Cluster, Collection & Entities\n## Entities\nEntities in a collection are data records sharing the same set of fields, like a book in a library or a gene in a genome. As to an entity, the data stored in each field forms the entity. \nBy specifying a query vector, search metrics, and optional filtering conditions, you can conduct vector searches among the entities in a collection. For example, if you search with the keyword \"Interesting Python demo\", any article whose title implies such semantic meaning will be returned as a relevant result. During this process, the search is actually conducted on the vector field **title_vector** to retrieve the top K nearest results. For details on vector searches, see [Search and Query](https://zilliverse.feishu.cn/wiki/YfMEwLHzeisARCk4VZ3cVhJmnjd). \nYou can add as many entities to a collection as you want. However, the size that an entity takes grows along with the increase of the dimensions of the vectors in the entity, reversely affecting the performance of searches within the collection. Therefore, plan your collection wisely on Zilliz Cloud by referring to [Schema Explained](https://zilliverse.feishu.cn/wiki/TqMFwNyDbiY9qekBfPNcbpuvnib)."
},
{
"id": 450524927755105958,
"distance": 0.046239592134952545,
"chunk_id": 1,
"doc_name": "zilliz_concept_doc.md",
"chunk_text": "# Cluster, Collection & Entities\n## Collection\n### Fields\nIn most cases, people describe an object in terms of its attributes, including size, weight, position, etc. These attributes of the object are similar to the fields in a collection. \nAmong all the fields in a collection, the primary key is one of the most special, because the values stored in this field are unique throughout the entire collection. Each primary key maps to a different record in the collection. \nIn the collection shown in Figure 1, the **id** field is the primary key. The first ID **0** maps to the article titled *The Mortality Rate of Coronavirus is Not Important*, and will not be used in any other records in this collection.\\n\\n# Cluster, Collection & Entities\n## Collection\n### Schema\nFields have their own properties, such as data types and related constraints for storing data in the field, like vector dimensions and distance metrics. By defining fields and their order, you will get a skeletal data structure termed schema, which shapes a collection in a way that resembles constructing the structure of a data table. \nFor your reference, Zilliz Cloud supports the following field data types: \n- Boolean value (BOOLEAN)\n- 8-byte floating-point (DOUBLE)\n- 4-byte floating-point (FLOAT)\n- Float vector (FLOAT_VECTOR)\n- 8-bit integer (INT8)\n- 32-bit integer (INT32)\n- 64-bit integer (INT64)\n- Variable character (VARCHAR)\n- [JSON](https://zilliverse.feishu.cn/wiki/H04VwNGoaimjcLkxoH4cs5TQnNd) \nZilliz Cloud provides three types of CUs, each of which have its own application scenarios, and they are also the factor that impacts search performance. \n> 📘 Notes\n>\n> **FLOAT_VECTOR** is the only data type that supports vector embeddings in Zilliz Cloud clusters."
}
],
"usage": {
"embedding": 24,
"rerank": 1437
}
}
}
删除文档数据
如需删除数据，请先创建并运行 Deletion Pipeline。
创建文档 Deletion Pipeline
- Cloud Console
- cURL
-
打开项目。
-
点击左侧导航栏中的 Pipelines。 选中概览标签页，并切换到 Pipelines。点击 + Pipeline。
-
选择需要创建的 Pipeline 类型。点击 Deletion Pipeline 一栏中的 + Pipeline 按钮。
-
配置 Deletion Pipeline。
参数
说明
Pipeline 名称
新创建的 Deleltion Pipeline 名称。名称中只可包含小写字母、数字和下划线。
描述 (可选)
对新创建的 Deletion Pipeline 的描述。
-
点击 + Function 添加 Function。您只可添加 1 个 Function。
-
输入 Function名称。
-
从 PURGE_DOC_INDEX 或 PURGE_BY_EXPRESSION 中选择 1 个作为 Function 类型。 PURGE_DOC_INDEX Function 可以删除指定名称的文档中所有的文档切片。PURGE_BY_EXPRESSION Function 可以删除符合指定过滤条件的所有 Entity。
-
点击添加。
-
-
点击添加。
以下示例代码创建了 1 个名称为 my_doc_deletion_pipeline 的 Deletion Pipeline，并添加了 1 个 PURGE_BY_EXPRESSION Function。
curl --request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines" \
-d '{
"projectId": "proj-xxxx",
"name": "my_doc_deletion_pipeline",
"description": "A pipeline that deletes all info associated with a doc",
"type": "DELETION",
"functions": [
{
"name": "purge_chunks_by_doc_name",
"action": "PURGE_DOC_INDEX"
}
],
"clusterId": "inxx-xxxxxxxxxxxxxxx",
"collectionName": "my_collection"
}'
以下为参数说明：
-
YOUR_API_KEY: 验证 API 请求的鉴权信息。了解如何查看 API 密钥。 -
cloud-region: 集群所在云服务地域的 ID。目前仅支持ali-cn-hangzhou。 -
projectId: 创建 Pipeline 所属的项目 ID。了解如何获取项目 ID。 -
name: 创建的 Pipeline 名称。Pipeline 名称应该在 3-64 个字符内，且只可包含数字、字母和下划线。 -
description(可选): 创建的 Pipeline 描述。 -
type: 创建的 Pipeline 类型。目 前，可创建的 Pipeline 类型包括INGESTION、SEARCH和DELETION。 -
functions: Pipeline 中添加的 Function。1 个 Deletion Pipeline 中仅可添加 1 个 Function。-
name: Function 名称。Function 名称应该在 3-64 个字符内，且只可包含数字、字母和下划线。 -
action: Function 类型。可选择的 Function 类型包含：PURGE_DOC_INDEX、PURGE_TEXT_INDEX、PURGE_BY_EXPRESSION和PURGE_IMAGE_INDEX。
-
-
clusterId: 创建 Pipeline 所属的集群 ID。目前，仅支持部署在阿里云（杭州）的集群。了解如何获取集群 ID。 -
collectionName: 创建 Pipeline 所属的 Collection 名称。
{
"code": 200,
"data": {
"pipelineId": "pipe-ab2874d8138c8554375bb0",
"name": "my_doc_deletion_pipeline",
"type": "DELETION",
"createTimestamp": 1721187655000,
"description": "A pipeline that deletes all info associated with a doc",
"status": "SERVING",
"functions": [
{
"action": "PURGE_DOC_INDEX",
"name": "purge_chunks_by_doc_name",
"inputField": "doc_name"
}
],
"clusterId": "in03-***************",
"collectionName": "my_collection"
}
}
运行文档 Deletion Pipeline
- Cloud Console
- cURL
-
点击 Deletion Pipeline 右侧的 "▶︎" 按钮。或者您可以点击 Playground 选项卡。
-
输入过滤表达式，点击运行。
-
查看运行结果。
以下示例代码用于运行 Deletion Pipeline my_doc_deletion_pipeline。
curl --request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines/${YOUR_PIPELINE_ID}/run" \
-d '{
"data": {
"doc_name": "zilliz_concept_doc.md",
}
}'
以下为参数说明：
-
YOUR_API_KEY: 验证 API 请求的鉴权信息。了解如何查看 API 密钥。 -
cloud-region: 集群的云服务地域。目前仅支持ali-cn-hangzhou。 -
doc_name: 需要删除的文档名称。如果输入的文档名称存在，该文档的所有文档切片都将被删除。如果文档名称不存在，该请求仍可执行，但是输出中的num_deleted_chunks值为 0。
请求返回以下类似内容：
{
"code": 200,
"data": {
"num_deleted_chunks": 567
}
}
以下操作可用于管理此前创建的 Pipeline。
查看 Pipeline
- Cloud Console
- cURL
点击左侧导航栏中的 Pipelines。选中 Pipelines 选项卡。您可以查看所有已创建的 Pipelines。
点击特定 Pipeline 名称，还可以查看其详情，包括基本信息、总用量、Functions、关联的 Connectors 等。
总用量非实时更新，数据统计可能会有几小时延迟。
您还可以查看所有 Pipelines 相关事件。
调用以下 API 查看所有 Pipelines 或查看某一特定 Pipeline 详情。
-
查看所有 Pipelines
根据以下示例并指定项目 ID
projectId。了解如何获取项目 ID。curl --request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines?projectId=proj-xxxx"如果请求返回以下类似内容，则表示操作成功：
{
"code": 200,
"data": [
{
"pipelineId": "pipe-xxxx",
"name": "my_doc_ingestion_pipeline",
"type": "INGESTION",
"description": "A pipeline that splits a doc file into chunks and generates embeddings. It also stores the publish_year with each chunk.",
"status": "SERVING",
"functions": [
{
"action": "INDEX_DOC",
"name": "index_my_doc",
"inputField": "doc_url",
"language": "ENGLISH",
"chunkSize": 500,
"embedding": "zilliz/bge-base-en-v1.5"
},
{
"action": "PRESERVE",
"name": "keep_doc_info",
"inputField": "publish_year",
"outputField": "publish_year",
"fieldType": "Int16"
}
],
"clusterId": "in03-***************",
"collectionName": "my_collection"
},
{
"pipelineId": "pipe-xxxx",
"name": "my_text_search_pipeline",
"type": "SEARCH",
"description": "A pipeline that receives text and search for semantically similar doc chunks",
"status": "SERVING",
"functions": [
{
"action": "SEARCH_DOC_CHUNK",
"name": "search_chunk_text_and_title",
"inputField": "query_text",
"clusterId": "in03-***************",
"collectionName": "my_collection",
"embedding": "zilliz/bge-base-en-v1.5"
}
]
},
{
"pipelineId": "pipe-xxxx",
"name": "my_doc_deletion_pipeline",
"type": "DELETION",
"description": "A pipeline that deletes all info associated with a doc",
"status": "SERVING",
"functions": [
{
"action": "PURGE_DOC_INDEX",
"name": "purge_chunks_by_doc_name",
"inputField": "doc_name"
}
],
"clusterId": "in03-***************",
"collectionName": "my_collection"
}
]
} -
查看特定 Pipeline 详情
根据以下示例查看某一 Pipeline 详情。
curl --request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines/${YOUR_PIPELINE_ID}"如果请求返回以下类似内容，则表示操作成功：
{
"code": 200,
"data": {
"pipelineId": "pipe-xxxx",
"name": "my_doc_ingestion_pipeline",
"type": "INGESTION",
"description": "A pipeline that splits a doc file into chunks and generates embeddings. It also stores the publish_year with each chunk.",
"status": "SERVING",
"functions": [
{
"action": "INDEX_DOC",
"name": "index_my_doc",
"inputField": "doc_url",
"language": "ENGLISH",
"chunkSize": 500,
"embedding": "zilliz/bge-base-en-v1.5"
},
{
"action": "PRESERVE",
"name": "keep_doc_info",
"inputField": "publish_year",
"outputField": "publish_year",
"fieldType": "Int16"
}
],
"clusterId": "in03-***************",
"collectionName": "my_collection"
}
}
删除 Pipeline
您可以删除不再需要使用的 Pipelines。该操作仅删除 Pipeline，不会影响自动创建的 Collection。
该操作仅删除 Pipeline，不会影响自动创建的 Collection。
Pipeline 一旦删除后不可恢复，请谨慎操作。
删除 Ingestion pipeline 时不会影响其相关联的 Collection。您的数据十分安全。
- Cloud Console
- cURL
如需删除不再使用的 Pipeline，请点击操作栏中的**“...”按钮并选择删除**。
根据以下示例删除 Pipelines。
curl --request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines/${YOUR_PIPELINE_ID}"
如果请求返回以下类似内容，则表示操作成功：
{
"code": 200,
"data": {
"pipelineId": "pipe-6ca5dd1b4672659d3c3487",
"name": "my_doc_ingestion_pipeline",
"type": "INGESTION",
"description": "A pipeline that splits a doc file into chunks and generates embeddings. It also stores the publish_year with each chunk.",
"status": "SERVING",
"functions": [
{
"action": "INDEX_DOC",
"name": "index_my_doc",
"inputField": "doc_url",
"language": "ENGLISH",
"chunkSize": 500,
"embedding": "zilliz/bge-base-en-v1.5"
},
{
"action": "PRESERVE",
"name": "keep_doc_info",
"inputField": "publish_year",
"outputField": "publish_year",
"fieldType": "Int16"
}
],
"clusterId": "in03-***************",
"collectionName": "my_collection"
}
}
管理 Pipeline
以下操作可用于管理此前创建的 Pipeline。
查看 Pipeline
- Cloud Console
- cURL
点击左侧导航栏中的 Pipelines。选中 Pipelines 选项卡。您可以查看所有已创建的 Pipelines。
点击特定 Pipeline 名称，还可以查看其详情，包括基本信息、总用量、Functions、关联的 Connectors 等。
总用量非实时更新，数据统计可能会有几小时延迟。
您还可以查看所有 Pipelines 相关事件。
调用以下 API 查看所有 Pipelines 或查看某一特定 Pipeline 详情。
-
查看所有 Pipelines
根据以下示例并指定项目 ID
projectId。了解如何获取项目 ID。curl --request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines?projectId=proj-xxxx"如果请求返回以下类似内容，则表示操作成功：
{
"code": 200,
"data": [
{
"pipelineId": "pipe-xxxx",
"name": "my_text_ingestion_pipeline",
"type": "INGESTION",
"createTimestamp": 1721187655000,
"clusterId": "in03-***************",
"collectionName": "my_collection"
"description": "A pipeline that generates text embeddings and stores additional fields.",
"status": "SERVING",
"totalUsage": {
"embedding": 0
},
"functions": [
{
"action": "INDEX_TEXT",
"name": "index_my_text",
"inputFields": ["text_list"],
"language": "ENGLISH",
"embedding": "zilliz/bge-base-en-v1.5"
},
{
"action": "PRESERVE",
"name": "keep_text_info",
"inputField": "source",
"outputField": "source",
"fieldType": "VarChar"
}
]
},
{
"pipelineId": "pipe-xxxx",
"name": "my_text_search_pipeline",
"type": "SEARCH",
"createTimestamp": 1721187655000,
"description": "A pipeline that receives text and search for semantically similar texts",
"status": "SERVING",
"totalUsage": {
"embedding": 0,
"rerank": 0
},
"functions":
{
"action": "SEARCH_TEXT",
"name": "search_text",
"inputFields": "query_text",
"clusterId": "in03-***************",
"collectionName": "my_collection",
"embedding": "zilliz/bge-base-en-v1.5",
"reranker": "zilliz/bge-reranker-base"
}
},
{
"pipelineId": "pipe-xxxx",
"name": "my_text_deletion_pipeline",
"type": "DELETION",
"createTimestamp": 1721187655000,
"description": "A pipeline that deletes entities by expression",
"status": "SERVING",
"functions":
{
"action": "PURGE_BY_EXPRESSION",
"name": "purge_data_by_expression",
"inputFields": ["expression"]
},
"clusterId": "in03-***************",
"collectionName": "my_collection"
}
]
}📘说明总用量
totalUsage非实时更新，数据统计可能会有几小时延迟。 -
查看特定 Pipeline 详情
根据以下示例查看某一 Pipeline 详情。
curl --request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines/${YOUR_PIPELINE_ID}"如果请求返回以下类似内容，则表示操作成功：
{
"code": 200,
"data": {
"pipelineId": "pipe-xxx",
"name": "my_text_ingestion_pipeline",
"type": "INGESTION",
"createTimestamp": 1721187300000,
"description": "A pipeline that generates text embeddings and stores additional fields.",
"status": "SERVING",
"totalUsage": {
"embedding": 0
},
"functions": [
{
"name": "index_my_text",
"action": "INDEX_TEXT",
"inputFields": ["text_list"],
"language": "ENGLISH",
"embedding": "zilliz/bge-base-en-v1.5"
},
{
"name": "keep_text_info",
"action": "PRESERVE",
"inputField": "source",
"outputField": "source",
"fieldType": "VarChar"
}
],
"clusterId": "inxx-xxxx",
"collectionName": "my_collection"
}
}📘说明总用量
totalUsage非实时更新，数据统计可能会有几小时延迟。
删除 Pipeline
您可以删除不再需要使用的 Pipelines。该操作仅删除 Pipeline，不会影响自动创建的 Collection。
该操作仅删除 Pipeline，不会影响自动创建的 Collection。
Pipeline 一旦删除后不可恢复，请谨慎操作。
删除 Ingestion pipeline 时不会影响其相关联的 Collection。您的数据十分安全。
- Cloud Console
- cURL
如需删除不再使用的 Pipeline，请点击操作栏中的**“...”按钮并选择删除**。
根据以下示例删除 Pipelines。
curl --request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer ${YOUR_API_KEY}" \
--url "https://controller.api.{cloud-region}.cloud.zilliz.com.cn/v1/pipelines/${YOUR_PIPELINE_ID}"
如果请求返回以下类似内容，则表示操作成功：
{
"code": 200,
"data": {
"pipelineId": "pipe-xxx",
"name": "my_text_ingestion_pipeline",
"type": "INGESTION",
"createTimestamp": 1721187300000,
"description": "A pipeline that generates text embeddings and stores additional fields.",
"status": "SERVING",
"totalUsage": {
"embedding": 0
},
"functions": [
{
"name": "index_my_text",
"action": "INDEX_TEXT",
"inputFields": ["text_list"],
"language": "ENGLISH",
"embedding": "zilliz/bge-base-en-v1.5"
},
{
"name": "keep_text_info",
"action": "PRESERVE",
"inputField": "source",
"outputField": "source",
"fieldType": "VarChar"
}
],
"clusterId": "inxx-xxxx",
"collectionName": "my_collection"
}
}
总用量 totalUsage 非实时更新，数据统计可能会有几小时延迟。