向量数据库 uploadUrl

该接口用于调用 AI 套件服务，获取上传文件所需的凭证。文件上传后，其内容将被直接拆分并写入指定的 Collection 中，而非 CollectionView。
说明：
当前支持导入 Collection 的文件类型包含： Markdown、PDF、Word、PPT。其中，仅 PDF 类型支持解析图片信息。
Method 与 URL
获取 COS 文件上传路径和授权签名凭证：POST https://{实例访问 IP 地址}:{实例网络端口}/ai/document/uploadUrl。
说明：
获取授权签名后，您需使用 COS（对象存储）SDK 或 Restful API 将文档上传至 COS 服务器。文件上传完成状态通知之后，向量数据库便会开始拉取文件并解析文件内容，进行拆分、向量化，创建索引并进行存储。
HTTP 上传文件的方式需要借助 COS 上传文件的接口，操作较繁琐，推荐使用向量数据库 Python SDK 的方式直接上传文件。
约束限制
每次仅能上传一个文件，上传之后，将自动进行拆分、向量化等。
该接口当前不支持使用别名获取文件的上传路径与授权。
注意：
在创建存储文件内容的 Collection 时，索引字段的设计需遵循以下限制与建议，否则可能导致上传文件失败。
文件名字段（file_name）：该字段必须定义为 string 类型的 filter 索引，以支持文件的过滤检索和处理同名文件覆盖的情况。字段名可以自定义，在上传文件时，需通过参数 field_mappings 的 filename 映射自定义的字段名。
文件内容字段（text）：该字段用于存储知识点的原始文本内容。由于文本内容可能较大，不建议为该字段创建索引，以避免占用过多内存空间。数据库会自动写入该字段的内容。在查询时，只需要通过 output_fields 参数指定该字段即可返回原始文本。字段名可以自定义，但需通过参数 field_mappings 的 text 映射自定义的字段名。
文件图片信息字段（image_list）：该字段存放 PDF 文件中图片的 Key 列表。在原始检索出的文本块中，图片位置将以 {key} 的形式进行占位。通过调用接口 getImageUrl，可以获取图片 URL 地址列表，这些地址与 Key 一一对应，从而实现将原始 PDF 文档恢复并展示为 HTML 格式。
不建议为该字段创建索引。如果需要创建索引，必须确保其为数组（array）类型，否则接口将报错，导致文件无法上传。
字段名可以自定义，但需要在上传文件时通过参数 field_mappings 的 imageList 映射到自定义的字段名。
请求参数
说明：
如果需要进行腾讯云向量数据库的测试，请获取 腾讯云向量数据库.pdf 文档。
curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
  http://10.0.X.X:80/ai/document/uploadUrl \\
  -d '{
    "database":"db-test",
    "collection":"coll-ai-files",
    "fileName": "腾讯云向量数据库.pdf",
    "splitterPreprocess": {
        "appendTitleToChunk": false,
        "appendKeywordsToChunk": true,
        "chunkSplitter": "\\n{2,}"
    },
    "parsingProcess": {
        "parsingType": "VisionModelParsing"
    },
    "embeddingModel": "bge-base-zh",
    "fieldMappings": {
        "filename": "file_name",
        "text": "text",
        "imageList": "image_list"
    }
  }'
参数
参数含义
子参数
是否必选
配置方法
database
指定 Database 名称。
-
是
使用 /database/list 获取集群中的数据库列表，复制数据库名。
collection
指定 Collection 的名称。
-
是
Collection 命名要求如下：
只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。
长度要求：[1,128]。
fileName
上传文件名称。
-
是
-
splitterPreprocess
文件预处理方式配置
appendTitleToChunk
否
在对文件拆分时，配置是否将 Title 追加到切分后的段落后面一并 Embedding。取值如下所示：
false：不追加。默认值为 false。
true：将段落 Title 追加到切分后的段落。
﻿
﻿
appendKeywordsToChunk
否
在对文件拆分时，配置是否将关键字 keywords 追加到切分后的段落一并 Embedding。取值如下所示：
false：不追加。
true：将全文的 keywords 追加到切分后的段落。默认值为 true。
﻿
﻿
chunkSplitter
否
以正则表达式的方式配置文档拆分方式，例如：
\\n{2,} 代表以两个及以上的换行进行拆分，常用在 QA 对文件拆分中。
parsingProcess
PDF 文件解析方式相关参数
parsingType
否
指定 PDF 类型文件的解析方式，取值如下所示：
VisionModelParsing：文件依据解析模型解析，推荐使用，可解析 PDF 中双栏、表格等复杂格式。
AlgorithmParsing：文件依据算法解析，系统默认解析方式。Markdown、Word、PPT 类型，无需配置该参数，默认使用 AlgorithmParsing 解析。
embeddingModel
指定使用的 Embedding 模型的名称。
-
是
您需根据业务的语言类型、数据维度要求等综合选择合适的模型。具体信息，参见 Embedding 介绍。取值如下所示：
bge-large-zh-v1.5：适用中文，1024维，推荐使用。
bge-base-zh-v1.5：适用中文，768维。
bge-large-zh：适用中文，1024维。
bge-base-zh：适用中文，768维。
m3e-base：适用中文，768维。
e5-large-v2：适用英文，1024维。
text2vec-large-chinese：适用中文，1024维。
multilingual-e5-base：适用于多种语言类型，768维。
BAAI/bge-m3：适用于多种语言类型，1024维。
fieldMappings
指定文件字段在数据库中映射关系。
filename
是
指定文件名映射的字段。例如："filename": "file_name"，其中，file_name 为自定义字段，用于在数据库中存储文件名信息。
注意：
必须定义为 string 类型的 filter 索引，以支持文件的过滤检索和处理同名文件覆盖的情况。
﻿
﻿
text
是
指定文件内容文本映射的字段，存储知识点的原始文本内容。例如："text": "text"，其中，text 为自定义字段，用于在数据库中存储文件的原始文本内容。
说明：
由于文本内容可能较大，不建议为该字段创建索引，以避免占用过多内存空间。数据库会自动写入该字段的内容。在查询时，只需要通过 output_fields 参数指定该字段即可返回原始文本。
﻿
﻿
image_list
是
指定图片信息存放的字段，存放 PDF 文件中图片的 Key 列表。例如："imageList": "image_list"，其中，image_list 为自定义的字段，用于在数据库中存储图片列表。
说明：
不建议为该字段创建索引。如果需要创建索引，必须确保其为数组（array）类型，否则接口将报错，导致文件无法上传。
响应信息
返回信息，如下所示。
{
  "code": 0,
  "msg": "Operation success",
  "requestId": "4b1bd009b5ee241839b18210070fdc1b",
  "cosEndpoint": "https://vecterdb-backup-gz-131891****.cos.ap-guangzhou.myqcloud.com",
  "cosRegion": "ap-guangzhou",
  "cosBucket": "vecterdb-backup-gz-131891****",
  "uploadPath": "embedding_file/vdb-jggo****/db-test/book-vector-1/腾讯云向量数据库.pdf",
  "credentials": {
    "TmpSecretId": "AKID****************************************************************",
    "TmpSecretKey": "******************************************",
    "Token": "********************************************************************************************",
    "Expiration": "2025-02-17T07:46:57Z",
    "ExpiredTime": 1739778417
  },
  "uploadCondition": {
    "maxSupportContentLength": 10485760
  }
}
接口 /ai/document/uploadurl  获取授权签名凭证之后，需使用 COS 接口上传文件，其与接口对应的参数解释如下所示。具体应用，请参见 使用 COS 接口上传文件。
VDB 参数名
参数含义
子参数
子参数含义
对应 COS SDK 参数名
COS 子参数
cosEndpoint
腾讯云对象存储（COS）的服务端点（Endpoint），即 COS 服务的访问地址。
-
-
cos_endpoint
-
﻿
cosBucket
COS 服务端存储桶名称。
-
-
-
-
﻿
cosRegion
COS 服务端存储桶所属地域。
-
-
cosRegion
-
uploadPath
依据数据库名、集合名、文件名拼接生成的 COS 端存放路径。
-
-
﻿
upload_path
-
credentials
COS 给该文件上传分配的临时身份凭证，以便在上传文件时进行身份验证和授权访问。
TmpSecretId
密钥 ID
﻿
credentials
﻿
SecretId
﻿
﻿
TmpSecretKey
密钥信息
﻿
SecretKey
﻿
﻿
Token
Token 信息
﻿
Token
uploadCondition
上传约束条件。
﻿
maxSupportContentLength
限制上传文件的最大字节数
maxSupportContentLength 
-
使用 COS Python SDK 上传文件示例
如下示例为 COS Python SDK 上传文件的参考代码。您需要根据代码注释替换相关授权凭证，以及如下表所列参数，便可以通过 upload_file() 接口上传文件。更多信息，请参见 COS Python SDK。
参数
是否必须
参数含义
﻿
local_file_path
是
本地上传路径。
cos_metadata
是
文件元数据库配置，配置方法，请参见如下代码示例注释。文件的 Metadata 元数据信息，可自定义扩展字段。例如：author、tags 等。
上传文件时，可为创建 CollectionView 设置的 Filter 索引的字段赋值，以便在检索时，使用该字段的 Filter 表达式检索文件。
上传文件时，可以新增标量字段，但新增字段不会构建 Filter 索引。
appendTitleToChunk
否
在对文件拆分时，配置是否将 Title 追加到切分后的段落后面一并 Embedding。取值如下所示：
0：不追加。默认值为0。
1：将段落 title 追加到切分后的段落。
appendKeywordsToChunk
否
在对文件拆分时，配置是否将关键字 keywords 追加到切分后的段落一并 Embedding。取值如下所示：
0：不追加。
1：将全文的 keywords 追加到切分后的段落。默认值为1。
chunkSplitter
否
以正则表达式的方式配置文档拆分方式，例如：
\\n{2,} 代表以两个及以上的换行进行拆分，常用在 QA 对文件拆分中。
parsingProcess
否
通过参数 parsingType 指定 PDF 类型文件的解析方式，取值如下所示：
VisionModelParsing：文件依据解析模型解析，推荐使用，可解析 PDF 中双栏、表格等复杂格式。
AlgorithmParsing：文件依据算法解析，系统默认解析方式。Markdown、Word、PPT 类型，无需配置该参数，默认使用 AlgorithmParsing 解析。
import requests
﻿
import json
import os
import sys
import urllib
import base64
from qcloud_cos import CosConfig, CosS3Client
﻿
local_file_path = "<your_local_file_path>"
﻿
# 1. json解析 /ai/documentSet/uploadUrl 获得的签名结果：
result = json.loads("<results from /ai/documentSet/uploadUrl>")
﻿
# 2. 文件Size校验(支持1MB Markdown文件)
limit_size = result["uploadCondition"]["maxSupportContentLength"]
file_stat = os.stat(local_file_path)
if limit_size < file_stat.st_size:
    print("The file exceeds its maximum permitted size")
    sys.exit(0)
﻿
# 3. 设置COS上传签名
credentials = result["credentials"]
print(credentials)
﻿
config = CosConfig(
    Region=result["cosRegion"],
    SecretId=credentials["TmpSecretId"],
    SecretKey=credentials["TmpSecretKey"],
    Token=credentials["Token"]
)
﻿
# 4. 您可以自定义文件 Metadata 信息
# 说明1：x-cos-meta-data，自定义属性及赋值，必填字段；{类型}支持string、uint64、array；{字段名}为元数据字段名，例如：author，page，city等。
metadata = {"fieldStr": "v1", "fieldInt": 1024, "fieldList": ["a", "b", "c"]}
# notice：必填字段，没有传：metadata = {}
# 说明2：chunk embedding增强参数
config = {"appendTitleToChunk": 1, "appendKeywordsToChunk": 1, "parsingProcess": {"parsingType": "VisionModelParsing"}} #上传文件时单独配置预处理逻辑
﻿
cos_metadata = {
    'x-cos-meta-id': result.get('documentSetId'),  # 文件唯一标识符，必填字段
    'x-cos-meta-config': urllib.parse.quote(base64.b64encode(json.dumps(config).encode('utf-8'))),
    'x-cos-meta-data': urllib.parse.quote(base64.b64encode(json.dumps(metadata).encode('utf-8')))
}
﻿
# 5. 上传文件：
CosS3Client(config).upload_file(
    Bucket=result.get('cosBucket'),
    Key=result.get('uploadPath'),
    LocalFilePath=local_file_path,  # 本地文件路径
    Metadata=cos_metadata
)
﻿

参数	参数含义	子参数	是否必选	配置方法
database	指定 Database 名称。	-	是	使用 /database/list 获取集群中的数据库列表，复制数据库名。
collection	指定 Collection 的名称。	-	是	Collection 命名要求如下：只能使用英文字母，数字，下划线_、中划线-，并以英文字母开头。长度要求：[1,128]。
fileName	上传文件名称。	-	是	-
splitterPreprocess	文件预处理方式配置	appendTitleToChunk	否	在对文件拆分时，配置是否将 Title 追加到切分后的段落后面一并 Embedding。取值如下所示： false：不追加。默认值为 false。 true：将段落 Title 追加到切分后的段落。
				appendKeywordsToChunk	否	在对文件拆分时，配置是否将关键字 keywords 追加到切分后的段落一并 Embedding。取值如下所示： false：不追加。 true：将全文的 keywords 追加到切分后的段落。默认值为 true。
				chunkSplitter	否	以正则表达式的方式配置文档拆分方式，例如： `\\n{2,}` 代表以两个及以上的换行进行拆分，常用在 QA 对文件拆分中。
parsingProcess	PDF 文件解析方式相关参数	parsingType	否	指定 PDF 类型文件的解析方式，取值如下所示： VisionModelParsing：文件依据解析模型解析，推荐使用，可解析 PDF 中双栏、表格等复杂格式。 AlgorithmParsing：文件依据算法解析，系统默认解析方式。Markdown、Word、PPT 类型，无需配置该参数，默认使用 AlgorithmParsing 解析。
embeddingModel	指定使用的 Embedding 模型的名称。	-	是	您需根据业务的语言类型、数据维度要求等综合选择合适的模型。具体信息，参见 Embedding 介绍。取值如下所示： bge-large-zh-v1.5：适用中文，1024维，推荐使用。 bge-base-zh-v1.5：适用中文，768维。 bge-large-zh：适用中文，1024维。 bge-base-zh：适用中文，768维。 m3e-base：适用中文，768维。 e5-large-v2：适用英文，1024维。 text2vec-large-chinese：适用中文，1024维。 multilingual-e5-base：适用于多种语言类型，768维。 BAAI/bge-m3：适用于多种语言类型，1024维。
fieldMappings	指定文件字段在数据库中映射关系。	filename	是	指定文件名映射的字段。例如："filename": "file_name"，其中，file_name 为自定义字段，用于在数据库中存储文件名信息。注意：必须定义为 string 类型的 filter 索引，以支持文件的过滤检索和处理同名文件覆盖的情况。
				text	是	指定文件内容文本映射的字段，存储知识点的原始文本内容。例如："text": "text"，其中，text 为自定义字段，用于在数据库中存储文件的原始文本内容。说明：由于文本内容可能较大，不建议为该字段创建索引，以避免占用过多内存空间。数据库会自动写入该字段的内容。在查询时，只需要通过 output_fields 参数指定该字段即可返回原始文本。
				image_list	是	指定图片信息存放的字段，存放 PDF 文件中图片的 Key 列表。例如："imageList": "image_list"，其中，image_list 为自定义的字段，用于在数据库中存储图片列表。说明：不建议为该字段创建索引。如果需要创建索引，必须确保其为数组（array）类型，否则接口将报错，导致文件无法上传。

VDB 参数名	参数含义	子参数	子参数含义	对应 COS SDK 参数名	COS 子参数
cosEndpoint	腾讯云对象存储（COS）的服务端点（Endpoint），即 COS 服务的访问地址。	-	-	`cos_endpoint`	-
cosBucket	COS 服务端存储桶名称。	-	-	-	-
cosRegion	COS 服务端存储桶所属地域。	-	-	`cosRegion`	-
uploadPath	依据数据库名、集合名、文件名拼接生成的 COS 端存放路径。	-	-	`upload_path`	-
credentials	COS 给该文件上传分配的临时身份凭证，以便在上传文件时进行身份验证和授权访问。	TmpSecretId	密钥 ID	`credentials`	`SecretId`
					TmpSecretKey	密钥信息	`SecretKey`
					Token	Token 信息	`Token`
uploadCondition	上传约束条件。	maxSupportContentLength	限制上传文件的最大字节数	`maxSupportContentLength`	-

参数	是否必须	参数含义
local_file_path	是	本地上传路径。
cos_metadata	是	文件元数据库配置，配置方法，请参见如下代码示例注释。文件的 Metadata 元数据信息，可自定义扩展字段。例如：author、tags 等。上传文件时，可为创建 CollectionView 设置的 Filter 索引的字段赋值，以便在检索时，使用该字段的 Filter 表达式检索文件。上传文件时，可以新增标量字段，但新增字段不会构建 Filter 索引。
appendTitleToChunk	否	在对文件拆分时，配置是否将 Title 追加到切分后的段落后面一并 Embedding。取值如下所示： 0：不追加。默认值为0。 1：将段落 title 追加到切分后的段落。
appendKeywordsToChunk	否	在对文件拆分时，配置是否将关键字 keywords 追加到切分后的段落一并 Embedding。取值如下所示： 0：不追加。 1：将全文的 keywords 追加到切分后的段落。默认值为1。
chunkSplitter	否	以正则表达式的方式配置文档拆分方式，例如： `\\n{2,}` 代表以两个及以上的换行进行拆分，常用在 QA 对文件拆分中。
parsingProcess	否	通过参数 parsingType 指定 PDF 类型文件的解析方式，取值如下所示： VisionModelParsing：文件依据解析模型解析，推荐使用，可解析 PDF 中双栏、表格等复杂格式。 AlgorithmParsing：文件依据算法解析，系统默认解析方式。Markdown、Word、PPT 类型，无需配置该参数，默认使用 AlgorithmParsing 解析。

uploadUrl

本页目录：

Method 与 URL

约束限制

请求参数

响应信息

使用 COS Python SDK 上传文件示例