調用UploadDocumentAsync非同步上傳文檔至文檔集合-雲原生資料倉儲AnalyticDB-阿里雲

非同步上傳文檔。

介面說明

伺服器根據副檔名載入並分割文檔，使用在調用 CreateDocumentCollection 操作時指定的嵌入模型進行向量化處理，然後將文檔寫入指定的文檔集合。此操作支援多種格式的文本和映像的多模態嵌入。

相關操作：

您可以調用 GetUploadDocumentJob 操作來查詢文檔上傳作業的進度和結果。
您可以調用 CancelUploadDocumentJob 操作來取消一個文檔上傳作業。

說明

在提交文檔上傳請求後，該請求將被排隊等待處理。在資源訪問管理（RAM）使用者或阿里雲帳號下，最多可以處理 20 個處於“待處理”和“運行中”狀態的文檔。
一個文字文件最多可以被分割成 100,000 個片段。
如果文檔集合使用了 OnePeace 模型，則每個 RAM 使用者或阿里雲帳號最多可以上傳並查詢 10,000 張圖片。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

gpdb:UploadDocumentAsync

create

*Document

acs:gpdb:{#regionId}:{#accountId}:document/{#DBInstanceId}

無

請求參數

名稱	類型	必填	描述	樣本值
DBInstanceId	string	是	啟用了向量引擎最佳化加速的執行個體 ID。您可以調用 DescribeDBInstances API 來查看目的地區域中所有 AnalyticDB PostgreSQL 執行個體的詳細資料，包括執行個體 ID。	gp-bp12ga6v69h86****
Collection	string	是	文件庫的名稱。說明由 CreateDocumentCollection API 建立. 您可以調用 ListDocumentCollections API 來查看已建立的文件庫。	document
Namespace	string	否	命名空間，預設為 public。您可以通過 CreateNamespace 介面建立一個命名空間，並通過 ListNamespaces 介面查看命名空間列表。	mynamespace
NamespacePassword	string	是	對應於命名空間的密碼。該值由 CreateNamespace 介面指定。	testpassword
RegionId	string	是	執行個體的地區 ID。	cn-hangzhou
FileName	string	是	文檔的檔案名稱。說明檔案名稱中需要添加副檔名。例如：.json、.md 和 .pdf。支援的影像檔副檔名包括：.bmp、.jpg、.jpeg、.png 和 .tiff。您可以使用壓縮包上傳映像。壓縮包的檔案名稱必須包含副檔名。支援的壓縮包副檔名包括：.tar、.gz 和 .zip。	mydoc.txt
FileUrl	string	是	公開訪問文檔的 URL。說明建議使用 SDK 調用此介面，SDK 提供了一個名為 UploadDocumentAsyncAdvance 的方法，可以直接上傳本地檔案。如果是映像歸檔 URL，當前歸檔中的映像數量不應超過 100 個重要 multimodal-embedding-v1 上傳圖片大小上限為 3MB	https://xx/mydoc.txt
Metadata	object	否	中繼資料。此參數的值必須與調用 CreateDocumentCollection 操作時指定的 Metadata 參數相同。
	any	否	中繼資料資訊，需和建立文件庫（CreateDocumentCollection）時指定的 Metadata 欄位一致。	{"title":"mytitle","page":1}
ChunkSize	integer	否	處理巨量資料的策略：當資料被分割成較小的部分時，每塊的大小。最大值為 2048。	250
ChunkOverlap	integer	否	連續塊之間重疊的資料大小。此參數的最大值不能大於 ChunkSize 參數的值。說明該參數用於防止由於資料截斷而導致的上下文丟失。例如，當您上傳長文本時，可以在連續的塊之間保留特定的重疊常值內容，以便更好地理解上下文。	50
Separators	array	否	用於分割大量資料的分隔字元。說明這是一個重要的參數，決定了資料分塊的效果。此參數與由 TextSplitterName 參數指定的分隔器相關。在大多數情況下，您不需要指定此參數。伺服器會根據 TextSplitterName 參數的值來分配分隔字元。
	string	否	分隔字元。	.
DryRun	boolean	否	指定是否僅執行文檔理解和分塊，而不進行向量化和儲存。預設值為 false。說明您可以將此參數設定為 true，檢查分塊效果，然後根據需要進行最佳化。	false
ZhTitleEnhance	boolean	否	指定是否啟用標題增強。說明您可以確定標題文本，在中繼資料中標記該文本，然後將該文本與上一級標題結合，以實現文本增強。	false
TextSplitterName	string	否	分隔器的名稱。有效值包括： ChineseRecursiveTextSplitter：繼承自 RecursiveCharacterTextSplitter, 預設使用`["\n\n","\n", "。\|!\|?", "\.\s\|\!\s\|\?\s", ";\|;\s", ",\|,\s"]` 為分隔字元，並使用Regex來匹配文本。 RecursiveCharacterTextSplitter: 預設使用`["\n\n", "\n", " ", ""]` 作為分隔字元。該分隔器支援分割如 C++, Go, Java, JS, PHP, Proto, Python, RST, Ruby, Rust, Scala, Swift, Markdown, LaTeX, HTML, Sol, 和 C Sharp 等語言的代碼. SpacyTextSplitter: 預設使用`\n\n` 作為分隔字元，並使用 spaCy 的 en_core_web_sm 模型。該分隔器可以獲得更好的分割效果。 MarkdownHeaderTextSplitter: 以[("#", "head1"), ("##", "head2"), ("###", "head3"), ("####", "head4")格式分割文本。該分隔器適用於 Markdown 文本。 LLMSplitter: 使用 LLM 對文本進行切分，預設模型使用 qwen3-8b。目前該分隔器僅在選用 ADBPGLoader 時生效。	ChineseRecursiveTextSplitter
DocumentLoaderName	string	否	文檔載入器的名稱。如果您不指定此參數，系統會根據副檔名自動按以下順序選擇相應的文檔載入器。有效值包括： UnstructuredHTMLLoader：.html UnstructuredMarkdownLoader：.md PyMuPDFLoader：.pdf PyPDFLoader：.pdf RapidOCRPDFLoader：.pdf PDFWithImageRefLoader：.pdf (with the text-image association feature) JSONLoader：.json CSVLoader：.csv RapidOCRLoader：.png、.jpg、.jpeg 和.bmp UnstructuredFileLoader: .eml、.msg、.rst、.txt、.docx、.epub、.odt、.pptx 和.tsv ADBPGLoader（收費，前 3000 頁免費）：.pdf、.doc、.docx、.ppt、.pptx、.xls、.xlsx、.xlsm、.csv、.txt、.jpg、.jpeg、.png、.bmp、.gif、.md、.html、.epub、.mobi 和.rtf	PyMuPDFLoader
VlEnhance	boolean	否	指定是否開啟複雜文檔的 VL 增強內容識別。預設值為 false。說明針對排版及格式較為混亂的複雜文檔，建議開啟 VL 增強內容識別。開啟 VL 增強內容識別後，文檔處理時間長度較長開啟 VL 增強內容識別後，文檔內的圖片暫不支援儲存及召回。	false
SplitterModel	string	否	在 DocumentLoaderName 選定 ADBPGLoader，且 TextSplitterName 選用 LLMSplitter 時，可指定切分模型。預設值為 qwen3-8b。說明當前支援的切分模型： qwq-plus，qwq-plus-latest， qwen-max，qwen-max-latest， qwen-plus，qwen-plus-latest， qwen-turbo，qwen-turbo-latest， qwen3-235b-a22b，qwen3-32b，qwen3-30b-a3b， qwen3-14b，qwen3-8b，qwen3-4b，qwen3-1.7b，qwen3-0.6b， qwq-32b qwen2.5-14b-instruct-1m，qwen2.5-7b-instruct-1m qwen2.5-72b-instruct，qwen2.5-32b-instruct， qwen2.5-14b-instruct，qwen2.5-7b-instruct, qwen2.5-3b-instruct，qwen2.5-1.5b-instruct，qwen2.5-0.5b-instruct	qwen3-8b

返回參數

名稱	類型	描述	樣本值
	object
RequestId	string	請求 ID。	ABB39CC3-4488-4857-905D-2E4A051D0521
Message	string	返回資訊。	success
Status	string	建立狀態，值描述：success：成功。fail：失敗。	success
JobId	string	任務 ID，用於後續檢查任務狀態或取消任務。	231460f8-75dc-405e-a669-0c5204887e91

樣本

正常返回樣本

JSON格式

{
  "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
  "Message": "success",
  "Status": "success",
  "JobId": "231460f8-75dc-405e-a669-0c5204887e91"
}

錯誤碼

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。