Document chunking - OpenSearch - Alibaba Cloud Documentation Center

AI Search Open Platform provides a document chunking service callable via an API. You can integrate this service into your business workflows to improve retrieval and processing efficiency.

Service name	Service ID	Description	API QPS limit
Document Chunking Service-001	ops-document-split-001	Provides general text chunking strategies to split structured data in HTML, Markdown, and plain text formats based on paragraph formatting, text semantics, or specified rules. It also supports extracting code blocks, images, and tables from rich text.	2 Note To request a higher API QPS limit, submit a ticket to technical support.

In Retrieval-Augmented Generation (RAG) pipelines, you typically convert documents into vectors and store them in a vector database for retrieval. The document chunking service divides long documents into smaller chunks that meet the length requirements of text embedding models. This process allows you to vectorize and retrieve content from very long documents.

Basic usage

The chunking API takes a plain text string and additional configuration options as input and returns the chunked text and potentially rich text elements. The API response contains four lists: chunks, nodes, rich_texts, and sentences. For the subsequent embedding step, extract the content from the chunks list and from the items in the rich_texts list whose type is not image. You can refer to the code template from the scenario center. The following Python code is an example:

# Extract the chunking results. Note that only ["chunks"] and ["rich_texts"] (excluding images) are used.
doc_list = []
for chunk in document_split_result.body.result.chunks:
    doc_list.append({"id": chunk.meta.get("id"), "content": chunk.content})
for rich_text in document_split_result.body.result.rich_texts:
    if rich_text.meta.get("type") != "image":
        doc_list.append({"id": rich_text.meta.get("id"), "content": rich_text.content})

Advanced usage

The document chunking service can split complex documents into chunks based on a specified token limit, creating a multi-node tree structure. You can use this tree structure during the retrieval phase in a RAG pipeline to add context to recalled chunks to improve the accuracy of the final response.

The service logic splits the text at the highest structural level possible. If a resulting chunk exceeds the specified length, the service recursively splits it until all chunks meet the length requirement. This recursive process forms a chunk tree, where each leaf node corresponds to a final chunk result, also known as a final node.

In the subsequent vector recall process, you can use the information from the chunk tree for context completion. For example, within your model's token limit, you can include sibling chunks from the same level as the recalled chunk to make the contextual information more complete.

For example, given the following text:

After you successfully enable the AI Search Open Platform service for the first time, the system automatically creates a default workspace: Default.
Click Create Workspace. Enter a custom workspace name, and then click Confirm. After you click Create new API key, the system generates an API key. You can then click the Copy button to copy and save the API key.

A possible chunk tree is as follows:

root (6b15)
  |
  +-- paragraph_node (557b)
       |
       +-- newline_node (ef4d)[After you successfully enable the AI Search Open Platform...Default.]
       |
       +-- newline_node (c618)
            |
            +-- sentence_node (98ce)[Click Create Workspace...and then click Confirm.]
            |
            +-- sentence_node (922a)[After you click Create new API key...to copy and save the API key.]

Given a maximum chunk size, the complete chunk tree contains two types of nodes: final nodes (nodes with chunk content) and intermediate nodes (logical nodes with no content). The service returns the entire tree as a list of all nodes (nodes) and the final nodes in a separate list (chunks). The following are some possible node types:

root: The root node.
paragraph_node: A paragraph node that represents a split based on the "\n\n" delimiter and identifies the position of a paragraph. Because the example does not contain "\n\n", there is only one such intermediate node.
newline_node: A newline node that represents a split based on the "\n" delimiter. In the example, the newline_node (ef4d) meets the chunk size requirement and is therefore a final node, whereas the newline_node (c618) requires further splitting and is an intermediate node.
sentence_node: A sentence node that represents a split based on a sentence delimiter, such as a period (.).
subsentence_node: A subsentence node that represents a split based on a clause delimiter, such as a comma (,). This type does not appear in the example.

For content provided in Markdown or HTML format, the service also extracts rich text elements into a separate rich_texts list. Examples of such elements include <img>, <table>, and <code> tags. In the chunked text, the service replaces the positions of these elements with placeholders like [image_0], <table>table_0</table>, and <code>code_0</code>. This design allows independent recall of rich text blocks and enables their reinsertion into the original context when needed. Each rich text block belongs to a unique final node chunk.

Additionally, to improve recall rates for short queries, you can set the strategy.need_sentence parameter to true. This instructs the service to split the original text by sentence and return the results in a separate sentences list, which can be used as an independent recall path. To facilitate sentence extension, each sentence block belongs to a unique final node chunk. Note that this sentences list is unrelated to the sentence_node type described earlier.

The bolded fields mentioned above—chunks, nodes, rich_texts, and sentences—are the fields returned by the API. You can find detailed usage information in the parameter descriptions that follow. For simplicity, the output of each chunk uses a simplified HTML syntax.

Prerequisites

Get authentication credentials

The AI Search open platform requires an API key for authentication. For instructions, see Get an API key.
Get the service endpoint

You can call the service via the public network or a VPC. For details, see Get the service endpoint.

Request specifications

General notes

The maximum size of the request body is 8 MB.

Request method

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/document-split/{service_id}

host: The endpoint for the service. You can call the service over the Internet or through a VPC. For more information, see Obtain service endpoints. The {host} placeholder is the API endpoint address. You can obtain it from the API key Management page in the left-side navigation pane of the AI Search Development Workbench. The API Endpoint section provides public API domains for Internet access and internal API domains for access from a VPC in the same region. Both domains support HTTPS.
workspace_name: The name of the workspace. For example, default.
service_id: The built-in service ID. For example, ops-document-split-001.

Request parameters

Header parameters

API key authentication

Parameter	Type	Required	Description	Example
Content-Type	String	Yes	The request type: `application/json`.	application/json
Authorization	String	Yes	The API key.	Bearer OS-d1**2a

Body parameters

Parameter	Type	Required	Description	Example
document.content	String	Yes	The plain text content to chunk. According to the JSON standard, the following special characters in a string field must be escaped: `\\`, `\"`, `\/`, `\b`, `\f`, `\n`, `\r`, and `\t`. JSON strings generated by common JSON libraries do not require manual escaping.	"Title\nFirst line\nSecond line"
document.content_encoding	String	No	The character encoding of the content. `utf8`: The default encoding type.	utf8
document.content_type	String	No	The format of the content. `html` `markdown` `text`: The default format (compatible with `plain` format).	html
strategy.type	String	No	The paragraph chunking strategy. `default`: The default strategy, which splits the document based on its paragraph structure.	default
strategy.max_chunk_size	Int	No	The maximum chunk length. Default value: 300.	300
strategy.compute_type	String	No	The method for calculating chunk length. `token`: The default method. Length is calculated based on the tokenizer of the `ops-text-embedding-001` vector model.	token
strategy.need_sentence	Boolean	No	Specifies whether to also return sentence-level chunks to optimize searches for short queries. Default value: `false`. Setting this parameter to `true` doubles token usage.	false
strategy.custom_split_label	String	No	Custom split string(s). When this parameter is not empty, only the custom strings are used for splitting; the default strategy is ignored. Multiple custom split strings can be specified, separated by commas (`,`). Default value: empty. Limitation: The custom split strings themselves cannot contain commas (`,`), as commas are used as the separator.	`"---"`: single value, splits only by `---` `"---,==="`: multiple values, splits by either `---` or `===`

Additional information:

The strategy.need_sentence parameter: Sentence-level chunking is a strategy independent of paragraph-level chunking. Each sentence is returned as an individual chunk. When sentence-level chunking is enabled, both short (sentence) and long (paragraph) chunks can be recalled simultaneously, complementing each other to improve overall recall rate.

Response parameters

Parameter	Type	Description	Example
request_id	String	The unique ID that the system assigns to the API call.	B4AB89C8-B135-****-A6F8-2BAB801A2CE4
latency	Float/Int	The time taken to process the request, in milliseconds (ms).	10
usage	Object	Billing information for the call.	"usage": { "token_count": 3072 }
usage.token_count	Int	The number of tokens.	3072
result.chunks	List(Chunk)	A list of chunking results (final nodes), containing the chunk content and metadata.	[{ "content" : "xxx", "meta":{'parent_id':x, 'id': x, 'type': 'text'} }]
result.chunks[].content	String	The content of the chunk.	"xxx"
result.chunks[].meta	Map	Metadata for the chunk. All the following fields are of the string type: `parent_id`: The ID of the parent node. `id`: The ID of the chunk node. `type`: The output type of the chunk content. Currently, the value is always `text`. `token`: The number of tokens in the current chunk.	{ 'parent_id': '3b94a18555c44b67b193c6ab4f**', 'id': 'c9edcb38fdf34add90d62f6bf5c6**, 'type': 'text' 'token': 10, }
result.rich_texts	List(RichText)	Rich text output. When `document.content_type` is `markdown` or `html`, the service replaces elements such as images, code, and tables in the content with placeholders. For example, an image URL `![image](www.example.com)` in the input content is replaced with the placeholder `[img_69646]`, and the corresponding rich text chunk is returned in the `rich_texts` list with an ID like `img_69646-0` (note the ID naming suffix). Note This format is not supported when `document.content_type` is `text`.	[{ "content" : "xxx", "meta":{'belonged_chunk_id':x, 'id': x, 'type': 'table'} }]
result.rich_texts[].content	String	The content of the rich text chunk. The `content` for an image is its URL, so it is not chunked and may exceed `max_chunk_size`. The service splits a table into a header and individual rows, and chunks code using the same method as plain text.	"<table><tr>\n<th>Action</th>\n<th>Description</th>\n</tr><tr>\n<td>Hide component</td>\n<td>Hides the component. No parameters are required.</td>\n</tr></table>"
result.rich_texts[].meta	Map	Metadata for the rich text chunk. All the following fields are of the string type: `belonged_chunk_id`: The ID of the chunk node to which this element belongs. Every rich text element belongs to one chunk node. `id`: The ID of the rich text element. `type`: The type of the element. Valid values: `code`, `image`, and `table`. `token`: The number of tokens in the current chunk. The token count for an image is always `-1`.	{ 'type': 'table', 'belonged_chunk_id': 'f0254cb7a5144a1fb3e5e024a3****b', 'id': 'table_2-1' 'token': 10 }
result.nodes	List(Node)	A list of all nodes in the chunk tree.	[{'parent_id':x, 'id': x, 'type': 'text'}]
result.nodes[]	Map	Information about a node in the chunk tree. All the following fields are of the string type: `id`: The node ID. If the node is also a chunk, this ID corresponds to the chunk ID. `type`: The type of the node. Valid values: `paragraph_node`, `newline_node`, `sentence_node`, and `subsentence_node`. For HTML or Markdown content, the type can also be `<h1>` to `<h6>`, representing different delimiters. `parent_id`: The ID of the parent node.	{ 'id': 'f0254cb7a5144a1fb3e5e024a3**b', 'type': 'paragraph_node', 'parent_id': 'f0254cb7a5144a1fb3e5e024a3**b' }
result.sentences (Optional)	List(sentence)	A list of sentences from each chunk is returned only when `strategy.need_sentence` in the request is `true`.	[{ "content" : "xxx", "meta":{'belonged_chunk_id':x, 'id': x, 'type': 'sentence'} }]
result.sentences[].content (Optional)	String	The content of the sentence.	"123"
result.sentences[].meta (Optional)	Map	Sentence metadata: `belonged_chunk_id`: The ID of the chunk node to which this sentence belongs. `id`: The sentence ID. `type`: The type of the element. The value is always `sentence`. `token`: The number of tokens in the current chunk.	{ 'id': 'f0254cb7a5144a1fb3e5e024a3**b1-1', 'type': 'sentence', 'belonged_chunk_id': 'f0254cb7a5144a1fb3e5e024a3**b', 'token': 10 }

cURL request example

curl -XPOST -H"Content-Type: application/json"  
"http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/default/document-split/ops-document-split-001"  
-H "Authorization: Bearer YOUR_API_KEY"  
-d "{
    \"document\":{
          \"content\":\"Product Advantages\\nIndustry Algorithm Edition\\nIntelligent\\nFeatures a rich set of customizable algorithm models and industry-specific recall and ranking algorithms to ensure superior search results.\\n\\nFlexible and Customizable\\nDevelopers can customize algorithm models, application structures, data processing, query analysis, and ranking configurations based on their business characteristics and data. This meets personalized search needs, increases click-through rates, enables rapid business iteration, and significantly shortens the time-to-market for new features.\\n\\nSecure and Stable\\nProvides 24/7 operational maintenance and technical support through online tickets and phone support. A comprehensive incident response mechanism includes fault monitoring, automatic alerts, and rapid issue identification. Access control and isolation are enforced at the API level by using Alibaba Cloud AccessKeyId and AccessKeySecret security pairs, ensuring user-level data segregation and security. Data is redundantly backed up to prevent loss.\\n\\nElastic Scaling\\nResources can be elastically scaled up or down as needed.\\n\\nRich Peripheral Features\\nSupports a range of peripheral search features such as hot searches, search suggestions, and statistical reports for convenient display and analysis.\\n\\nOut-of-the-Box\\nNo need to deploy or maintain clusters. Quickly access a one-stop search service.\\n\\nHigh-Performance Retrieval Edition\\nHigh Throughput\\nSupports tens of thousands of write TPS for a single table, with updates in seconds.\\n\\nSecure and Stable\\nProvides 24/7 operational maintenance and technical support through online tickets and phone support. A comprehensive incident response mechanism includes fault monitoring, automatic alerts, and rapid issue identification. Access control and isolation are enforced at the API level by using Alibaba Cloud AccessKeyId and AccessKeySecret security pairs, ensuring user-level data segregation and security. Data is redundantly backed up to prevent loss.\\n\\nElastic Scaling\\nResources can be elastically scaled up or down as needed.\\n\\nOut-of-the-Box\\nNo need to deploy or maintain clusters. Quickly access a one-stop search service.\\n\\nVector Retrieval Edition\\nStable\\nThe underlying implementation in C++ has been developed for over a decade and supports multiple core businesses, making it highly stable and suitable for mission-critical search scenarios.\\n\\nEfficient\\nA distributed search engine that efficiently supports massive data retrieval and real-time data updates (effective in seconds), making it ideal for search scenarios that are sensitive to query latency and timeliness.\\n\\nCost-Effective\\nSupports multiple index compression strategies and multi-value index loading tests to meet user query needs at a lower cost.\\n\\nVector Algorithms\\nSupports vector retrieval for various unstructured data such as voice, images, videos, text, and behaviors.\\n\\nSQL Queries\\nSupports SQL syntax and online multi-table joins. Provides a rich set of built-in UDFs and a UDF customization mechanism to meet diverse retrieval needs. SQL Studio is integrated into the operations system for easy SQL development and testing.\\n\\nRecall Engine Edition\\nStable\\nThe underlying implementation in C++ has been developed for over a decade and supports multiple core businesses, making it highly stable and suitable for mission-critical search scenarios.\\n\\nEfficient\\nThe Wentian Engine is a distributed search engine that efficiently supports massive data retrieval and real-time data updates (effective in seconds), making it ideal for search scenarios that are sensitive to query latency and timeliness.\\n\\nCost-Effective\\nThe Wentian Engine supports multiple index compression strategies and multi-value index loading tests to meet user query needs at a lower cost.\\n\\nFeature-Rich\\nThe Wentian Engine supports various analyzer types, index types, and powerful query syntax to meet user retrieval needs. A plugin mechanism is also provided for customizing business logic.\\n\\nSQL Queries\\nThe Wentian Engine supports SQL syntax and online multi-table joins. Provides a rich set of built-in UDFs and a UDF customization mechanism to meet diverse retrieval needs. SQL Studio will soon be integrated into the operations system for easy SQL development and testing.\",
          \"content_encoding\":\"utf8\",\"content_type\":\"text\"
    },
    \"strategy\":{
          \"type\":\"default\",
          \"max_chunk_size\":300,
          \"compute_type\":\"token\",
          \"need_sentence\":false
    }
}"

Response examples

Successful response

{
	"request_id": "47EA146B-****-448C-A1D5-50B89D7EA434",
	"latency": 161,
	"usage": {
		"token_count": 800
	},
	"result": {
		"chunks": [
			{
				"content": "Product Advantages\\nIndustry Algorithm Edition\\nIntelligent\\nFeatures a rich set of customizable algorithm models and industry-specific recall and ranking algorithms to ensure superior search results.\\n\\nFlexible and Customizable\\nDevelopers can customize algorithm models, application structures, data processing, query analysis, and ranking configurations based on their business characteristics and data. This meets personalized search needs, increases click-through rates, enables rapid business iteration, and significantly shortens the time-to-market for new features.\\n\\nSecure and Stable\\nProvides 24/7 operational maintenance and technical support through online tickets and phone support. A comprehensive incident response mechanism includes fault monitoring, automatic alerts, and rapid issue identification. Access control and isolation are enforced at the API level by using Alibaba Cloud AccessKeyId and AccessKeySecret security pairs, ensuring user-level data segregation and security. Data is redundantly backed up to prevent loss.\\n\\nElastic Scaling\\nResources can be elastically scaled up or down as needed.\\n\\nRich Peripheral Features\\nSupports a range of peripheral search features such as hot searches, search suggestions, and statistical reports for convenient display and analysis.\\n\\nOut-of-the-Box\\nNo need to deploy or maintain clusters. Quickly access a one-stop search service.\\n\\nHigh-Performance Retrieval Edition\\nHigh Throughput\\nSupports tens of thousands of write TPS for a single table, with updates in seconds",
				"meta": {
					"parent_id": "dee776dda3ff4b078bccf989a6bd****",
					"id": "27eea7c6b2874cb7a5bf6c71afbf****",
					"type": "text"
				}
			},
			{
				"content": ".\\n\\nSecure and Stable\\nProvides 24/7 operational maintenance and technical support through online tickets and phone support. A comprehensive incident response mechanism includes fault monitoring, automatic alerts, and rapid issue identification. Access control and isolation are enforced at the API level by using Alibaba Cloud AccessKeyId and AccessKeySecret security pairs, ensuring user-level data segregation and security. Data is redundantly backed up to prevent loss.\\n\\nElastic Scaling\\nResources can be elastically scaled up or down as needed.\\n\\nOut-of-the-Box\\nNo need to deploy or maintain clusters. Quickly access a one-stop search service.\\n\\nVector Retrieval Edition\\nStable\\nThe underlying implementation in C++ has been developed for over a decade and supports multiple core businesses, making it highly stable and suitable for mission-critical search scenarios.\\n\\nEfficient\\nA distributed search engine that efficiently supports massive data retrieval and real-time data updates (effective in seconds), making it ideal for search scenarios that are sensitive to query latency and timeliness.\\n\\nCost-Effective\\nSupports multiple index compression strategies and multi-value index loading tests to meet user query needs at a lower cost.\\n\\nVector Algorithms\\nSupports vector retrieval for various unstructured data such as voice, images, videos, text, and behaviors.\\n\\nSQL Queries\\nSupports SQL syntax and online multi-table joins. Provides a rich set of built-in UDFs and a UDF customization mechanism to meet diverse retrieval needs",
				"meta": {
					"parent_id": "dee776dda3ff4b078bccf989a6bd****",
					"id": "bf9fcfb47fcf410aa05216e268df****",
					"type": "text"
				}
			},
			{
				"content": ". SQL Studio is integrated into the operations system for easy SQL development and testing.\\n\\nRecall Engine Edition\\nStable\\nThe underlying implementation in C++ has been developed for over a decade and supports multiple core businesses, making it highly stable and suitable for mission-critical search scenarios.\\n\\nEfficient\\nThe Wentian Engine is a distributed search engine that efficiently supports massive data retrieval and real-time data updates (effective in seconds), making it ideal for search scenarios that are sensitive to query latency and timeliness.\\n\\nCost-Effective\\nThe Wentian Engine supports multiple index compression strategies and multi-value index loading tests to meet user query needs at a lower cost.\\n\\nFeature-Rich\\nThe Wentian Engine supports various analyzer types, index types, and powerful query syntax to meet user retrieval needs. A plugin mechanism is also provided for customizing business logic.\\n\\nSQL Queries\\nThe Wentian Engine supports SQL syntax and online multi-table joins. Provides a rich set of built-in UDFs and a UDF customization mechanism to meet diverse retrieval needs. SQL Studio will soon be integrated into the operations system for easy SQL development and testing.",
				"meta": {
					"parent_id": "dee776dda3ff4b078bccf989a6bd****",
					"id": "26ab0e4f7665487bb0a82c5a226a****",
					"type": "text"
				}
			}
		],
		"nodes": [
			{
				"id": "dee776dda3ff4b078bccf989a6bd****",
				"type": "root",
				"parent_id": "dee776dda3ff4b078bccf989a6bd****"
			},
			{
				"id": "27eea7c6b2874cb7a5bf6c71afbf****",
				"type": "sentence",
				"parent_id": "dee776dda3ff4b078bccf989a6bd****"
			},
			{
				"id": "bf9fcfb47fcf410aa05216e268df****",
				"type": "sentence",
				"parent_id": "dee776dda3ff4b078bccf989a6bd****"
			},
			{
				"id": "26ab0e4f7665487bb0a82c5a226a****",
				"type": "sentence",
				"parent_id": "dee776dda3ff4b078bccf989a6bd****"
			}
		],
		"rich_texts": []
	}
}

Error response

If an error occurs, the response includes code and message fields that indicate the cause.

{
    "request_id": "817964CD-1B84-4AE1-9B63-4FB99734****",
    "latency": 0,
    "code": "InvalidParameter",
    "message": "JSON parse error: Invalid UTF-8 start byte 0xbc; nested exception is com.fasterxml.jackson.core.JsonParseException: Invalid UTF-8 start byte 0xbc\n at line: 2, column: 19]"
}

Status codes

For more information, see Status codes for AI Search Open Platform.