API详情

服务介绍

文档切片服务可将复杂的文档内容按照指定token数量进行切分，最终形成一个由多节点组成的树形结构。树形结构可以用于RAG的retrieval阶段，补全召回切片的上下文信息，实现更高的回答准确率。

文档切片服务的逻辑是尽可能得将文本按照最宏观的结构去切分，如果此时每个切片的长度不能满足要求，那么则会递归地继续切分每个切片，直到所有的切片长度都符合要求。递归切分的过程形成了一棵切片树，其中每个叶子节点对应了一个真正的切片结果，即最终节点。

在后续的向量召回切片的过程中，您可以使用切片树的信息做上下文补全。例如，可以在模型token数限制范围内将召回切片的同一级其他切片一同补齐，提高信息的完整度。

例如，给出一段文本

首次开通搜索开发工作台服务成功后，系统会自动创建出一个默认的工作空间：Default。
点击创建空间。输入自定义的工作空间名称，点击确认即可。点击创建新的API-KEY后，系统会创建生成API-KEY，此处客户可以点击复制按钮将API-KEY的内容复制保存。

以下是一个可能的切片树：

root (6b15)
  |
  +-- paragraph_node (557b)
       |
       +-- newline_node (ef4d)[首次开通搜索开发工作台...Default。]
       |
       +-- newline_node (c618)
            |
            +-- sentence_node (98ce)[点击创建空间...点击确认即可。]
            |
            +-- sentence_node (922a)[点击创建新的API-KEY后...复制按钮将API-KEY的内容复制保存。]

在指定切片最大长度的前提下，完整的切片树包含最终节点（有切片内容的节点）及中间节点（不包含任何内容，仅为逻辑节点）两种类型。整棵树会以所有节点列表的形式被返回（nodes），同时最终节点还会在一个列表中单独返回（chunks）。以下是可能出现的一些节点种类：

• root：根节点

• paragraph_node：段落节点，代表对于"\n\n"分隔符的切分，用于标识段落位置（示例中无\n\n，因此只有一个这样的中间节点）

• newline_node：换行节点，代表对于"\n"分隔符的切分（示例中newline_node (ef4d)节点满足切片长度要求，则为最终节点；newline_node (c618)节点需进一步切分，则为中间节点）

• sentence_node：句子节点，代表对于“。”的切分

• subsentence_node：子句节点，代表对于“，”的切分（示例未出现）

对于以markdown和html格式输入的内容，切片服务还会将一些富文本（rich_texts）单独输出。例如html中的<img>,<table>,<code> tags. 这些富文本在切片原文中的位置将会被替换成[image_0]，<table>table_0</table>, <code>code_0</code>，于此同时每个富文本块都会在rich_texts字段被返回。这样的设计方便单独召回富文本块，也可以在需要时放回原文中去。每个富文本块都归属于唯一切片的最终节点chunk。

此外，为了提升短query的召回率，客户可以选择配置strategy.need_sentence=true。此时会将原文按句子做切分并单独返回sentences列表，可以作为一路独立召回。为了方便扩展sentence，每个sentence块都归属于唯一的切片的最终节点chunk。（注意这个sentences列表和上面的sentence_node没有关系）

上文中的红字chunks，nodes，rich_texts，sentences就是API返回的全部字段了，您可以在下面的参数描述中找到详细用法。

前提条件

当前API支持2种鉴权方式，您可选择以下任一种方式进行鉴权：

API-KEY鉴权，前提条件：

• 已开通服务并获得API-KEY：开通服务并创建API-KEY。

AccessKey鉴权，前提条件：

• 已开通服务并配置环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET：创建AccessKey并配置环境变量。

请求说明

公共说明

• 请求body最大不能超过8MB。

请求方式

POST

URL

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

• host：调用服务的地址，可参考控制台-API-KEY管理页面的生产API域名，例： http://******.hangzhou.opensearch.aliyuncs.com

• workspace_name：工作空间名称，例：default

• service_id： 系统内置服务id，例：ops-document-split-001

入参描述

Header参数

• API-KEY鉴权

• AccessKey鉴权请参考：v3 API 签名机制

Body参数

补充说明：

• strategy.need_sentence参数：sentence级别切片是一种独立于段落切片的策略，简单来说就是将每一句话都作为独立的切片返回。开启sentence级别切片策略后，短切片及长切片可以同时召回，作为相互补充提升整体召回率。

出参描述

请求示例

curl示例

curl -XPOST -H"Content-Type: application/json" \http: //workspace01-8ey.platform-pre-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/workspace01/document-split/ops-document-split-001\
    -H "Authorization: Bearer 你的API-KEY" \
    -d '{
    "document": {
        "content": "产品优势\n行业算法版\n智能\n内置丰富的定制化算法模型，并结合不同行业搜索特点，推出行业召回、排序算法，保障更优搜索效果。\n\n灵活、可定制\n开发者可基于自身业务特性与数据，定制相应的算法模型、应用结构、数据处理、查询分析、排序等配置，满足个性化搜索需求，提升搜索结果点击率，实现业务快速迭代，极大缩短需求上线的周期。\n\n安全、稳定\n提供7×24小时的运行维护，并以在线工单和电话报障等方式提供技术支持，具备完善的故障监控、自动告警、快速定位等一系列故障应急响应机制。基于阿里云的AccessKeyId和AccessKeySecret安全加密对，从访问接口上进行权限控制和隔离，保证用户级别的数据隔离，用户数据安全有保障。数据冗余备份，保证数据不会丢失。\n\n弹性伸缩\n具备弹性扩容能力，用户可根据需要自行扩展或缩减所使用的资源。\n\n丰富的外围功能\n支持热搜、底纹、下拉提示、统计报表等一系列搜索外围功能，方便用户展示及分析。\n\n开箱即用\n无需运维部署集群，快速一站式接入搜索服务\n\n高性能检索版\n高吞吐\n单表支持万级别的写入TPS，秒级更新。\n\n安全、稳定\n提供7×24小时的运行维护，并以在线工单和电话报障等方式提供技术支持，具备完善的故障监控、自动告警、快速定位等一系列故障应急响应机制。基于阿里云的AccessKeyId和AccessKeySecret安全加密对，从访问接口上进行权限控制和隔离，保证用户级别的数据隔离，用户数据安全有保障。数据冗余备份，保证数据不会丢失。\n\n弹性伸缩\n具备弹性扩容能力，用户可根据需要自行扩展或缩减所使用的资源。\n\n开箱即用\n无需运维部署集群，快速一站式接入搜索服务\n\n向量检索版\n稳定\n底层采用c++实现，经过十多年的发展，支撑了多个核心业务，非常稳定，非常适用于对稳定性要求较高的核心搜索场景。\n\n高效\n分布式搜索引擎，可以高效的支持海量数据的检索，同时也支持数据的实时更新（秒级生效），非常适用于对查询耗时敏感、时效性要求高的搜索场景。\n\n低成本\n支持多种索引压缩策略，同时支持多值索引加载测试，能够以较低的成本满足用户的查询需求。\n\n向量算法\n支持各种非结构化数据（如语音、图片、视频，语言文字、行为等）向量检索。\n\nSQL查询\n支持SQL查询语法，支持多表在线join，提供丰富的内置UDF函数和UDF函数定制机制，以满足不同用户的检索需求。在运维系统中我们已经集成SQL studio，方便用户进行SQL开发和测试。\n\n召回引擎版\n稳定\n底层采用c++实现，经过十多年的发展，支撑了多个核心业务，非常稳定，非常适用于对稳定性要求较高的核心搜索场景。\n\n高效\n问天引擎是一个分布式搜索引擎，可以高效的支持海量数据的检索，同时也支持数据的实时更新（秒级生效），非常适用于对查询耗时敏感、时效性要求高的搜索场景。\n\n低成本\n问天引擎支持多种索引压缩策略，同时支持多值索引加载测试，能够以较低的成本满足用户的查询需求。\n\n功能丰富\n问天引擎支持多种分析器类型、多种索引类型、强大的查询语法，能够很好的满足用户的检索需求。同时我们还提供插件机制，方便用户定制自己的业务处理逻辑。\n\nSQL查询\n问天引擎支持SQL查询语法，支持多表在线join，提供丰富的内置UDF函数和UDF函数定制机制，以满足不同用户的检索需求。在运维系统中我们即将集成SQL studio，方便用户进行SQL开发和测试。",
        "content_encoding": "utf8",
        "content_type": "text"
    },
    "strategy": {
        "type": "default",
        "max_chunk_size": 300,
        "compute_type": "token",
        "need_sentence": false
    }
}'

windows系统下curl示例

curl -XPOST -H"Content-Type: application/json"  "http://workspace01-8ey.platform-pre-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/workspace01/document-split/ops-document-split-001"  -H "Authorization: Bearer OS-o73vw0u7158sqo9r"  -d "{\"document\":{\"content\":\"产品优势\\n行业算法版\\n智能\\n内置丰富的定制化算法模型，并结合不同行业搜索特点，推出行业召回、排序算法，保障更优搜索效果。\\n\\n灵活、可定制\\n开发者可基于自身业务特性与数据，定制相应的算法模型、应用结构、数据处理、查询分析、排序等配置，满足个性化搜索需求，提升搜索结果点击率，实现业务快速迭代，极大缩短需求上线的周期。\\n\\n安全、稳定\\n提供7×24小时的运行维护，并以在线工单和电话报障等方式提供技术支持，具备完善的故障监控、自动告警、快速定位等一系列故障应急响应机制。基于阿里云的AccessKeyId和AccessKeySecret安全加密对，从访问接口上进行权限控制和隔离，保证用户级别的数据隔离，用户数据安全有保障。数据冗余备份，保证数据不会丢失。\\n\\n弹性伸缩\\n具备弹性扩容能力，用户可根据需要自行扩展或缩减所使用的资源。\\n\\n丰富的外围功能\\n支持热搜、底纹、下拉提示、统计报表等一系列搜索外围功能，方便用户展示及分析。\\n\\n开箱即用\\n无需运维部署集群，快速一站式接入搜索服务\\n\\n高性能检索版\\n高吞吐\\n单表支持万级别的写入TPS，秒级更新。\\n\\n安全、稳定\\n提供7×24小时的运行维护，并以在线工单和电话报障等方式提供技术支持，具备完善的故障监控、自动告警、快速定位等一系列故障应急响应机制。基于阿里云的AccessKeyId和AccessKeySecret安全加密对，从访问接口上进行权限控制和隔离，保证用户级别的数据隔离，用户数据安全有保障。数据冗余备份，保证数据不会丢失。\\n\\n弹性伸缩\\n具备弹性扩容能力，用户可根据需要自行扩展或缩减所使用的资源。\\n\\n开箱即用\\n无需运维部署集群，快速一站式接入搜索服务\\n\\n向量检索版\\n稳定\\n底层采用c++实现，经过十多年的发展，支撑了多个核心业务，非常稳定，非常适用于对稳定性要求较高的核心搜索场景。\\n\\n高效\\n分布式搜索引擎，可以高效的支持海量数据的检索，同时也支持数据的实时更新（秒级生效），非常适用于对查询耗时敏感、时效性要求高的搜索场景。\\n\\n低成本\\n支持多种索引压缩策略，同时支持多值索引加载测试，能够以较低的成本满足用户的查询需求。\\n\\n向量算法\\n支持各种非结构化数据（如语音、图片、视频，语言文字、行为等）向量检索。\\n\\nSQL查询\\n支持SQL查询语法，支持多表在线join，提供丰富的内置UDF函数和UDF函数定制机制，以满足不同用户的检索需求。在运维系统中我们已经集成SQL studio，方便用户进行SQL开发和测试。\\n\\n召回引擎版\\n稳定\\n底层采用c++实现，经过十多年的发展，支撑了多个核心业务，非常稳定，非常适用于对稳定性要求较高的核心搜索场景。\\n\\n高效\\n问天引擎是一个分布式搜索引擎，可以高效的支持海量数据的检索，同时也支持数据的实时更新（秒级生效），非常适用于对查询耗时敏感、时效性要求高的搜索场景。\\n\\n低成本\\n问天引擎支持多种索引压缩策略，同时支持多值索引加载测试，能够以较低的成本满足用户的查询需求。\\n\\n功能丰富\\n问天引擎支持多种分析器类型、多种索引类型、强大的查询语法，能够很好的满足用户的检索需求。同时我们还提供插件机制，方便用户定制自己的业务处理逻辑。\\n\\nSQL查询\\n问天引擎支持SQL查询语法，支持多表在线join，提供丰富的内置UDF函数和UDF函数定制机制，以满足不同用户的检索需求。在运维系统中我们即将集成SQL studio，方便用户进行SQL开发和测试。\",\"content_encoding\":\"utf8\",\"content_type\":\"text\"},\"strategy\":{\"type\":\"default\",\"max_chunk_size\":300,\"compute_type\":\"token\",\"need_sentence\":false}}"

响应示例

正常响应示例

{
	"request_id": "47EA146B-xxxx-448C-A1D5-50B89D7EA434",
	"latency": 161,
	"usage": {
		"token_count": 800
	},
	"result": {
		"chunks": [
			{
				"content": "产品优势\\n行业算法版\\n智能\\n内置丰富的定制化算法模型，并结合不同行业搜索特点，推出行业召回、排序算法，保障 更优搜索效果。\\n\\n灵活、可定制\\n开发者可基于自身业务特性与数据，定制相应的算法模型、应用结构、数据处理、查询分析、排序等配置，满足个性化搜索需求，提升搜索结果点击率，实现业务快速迭代，极大缩短需求上线的周期。\\n\\n安全、稳定\\n提供7×24小时的运行维护，并以在线工单和电话报障等方式提供技术支持，具备完善的故障监控、自动告警、快速定位等一系列故障应急响应机制。基于阿里云的AccessKeyId和AccessKeySecret安全加密对，从访问接口上进行权限控制和隔离，保证用户级别的数据隔离，用户 数据安全有保障。数据冗余备份，保证数据不会丢失。\\n\\n弹性伸缩\\n具备弹性扩容能力，用户可根据需要自行扩展或缩减所使用的资源。\\n\\n丰富的外围功能\\n支持热搜、底纹、下拉提示、统计报表等一系列搜索外围功能，方便用户展示及分析。\\n\\n开箱即 用\\n无需运维部署集群，快速一站式接入搜索服务\\n\\n高性能检索版\\n高吞吐\\n单表支持万级别的写入TPS，秒级更新",
				"meta": {
					"parent_id": "dee776dda3ff4b078bccf989a6bda9c6",
					"id": "27eea7c6b2874cb7a5bf6c71afbfa32e",
					"type": "text"
				}
			},
			{
				"content": "。\\n\\n安全、稳定\\n提供7×24小时的运行维护，并以在线工单和电话报障等方式提供技术支持，具备完善的故障监控、自动告警、快速定位等一系列故障应急响应机制。基于阿里云的AccessKeyId和AccessKeySecret安全加密对，从访问接口上进行权限控制和隔离，保证 用户级别的数据隔离，用户数据安全有保障。数据冗余备份，保证数据不会丢失。\\n\\n弹性伸缩\\n具备弹性扩容能力，用户可根据需要自行扩展或缩减所使用的资源。\\n\\n开箱即用\\n无需运维部署集群，快速一站式接入搜索服务\\n\\n向量检索版\\n稳定\\n底层 采用c++实现，经过十多年的发展，支撑了多个核心业务，非常稳定，非常适用于对稳定性要求较高的核心搜索场景。\\n\\n高效\\n分布式搜索引擎，可以高效的支持海量数据的检索，同时也支持数据的实时更新（秒级生效），非常适用于对查询耗时敏感、时效性要求 高的搜索场景。\\n\\n低成本\\n支持多种索引压缩策略，同时支持多值索引加载测试，能够以较低的成本满足用户的查询需求。\\n\\n向量算法\\n支持各种非结构化数据（如语音、图片、视频，语言文字、行为等）向量检索。\\n\\nSQL查询\\n支持SQL查询语法，支持多表在线join，提供丰富的内置UDF函数和UDF函数定制机制，以满足不同用户的检索需求",
				"meta": {
					"parent_id": "dee776dda3ff4b078bccf989a6bda9c6",
					"id": "bf9fcfb47fcf410aa05216e268df2b2d",
					"type": "text"
				}
			},
			{
				"content": "。在运维系统中我们已经集成SQL studio，方便用户进行SQL开发和测试。\\n\\n召回引擎版\\n稳定\\n底层采用c++实现，经过十多年的发展，支撑了多个核心业务，非常稳定，非常适用于对稳定性要求较高的核心搜索场景。\\n\\n高效\\n问天引擎是一个分布式搜索引擎，可以高效的支持海量数据的检索，同时也支持数据的实时更新（秒级生效），非常适用于对查询耗时敏感、时效性要求高的搜索场景。\\n\\n低成本\\n问天引擎支持多种索引压缩策略，同时支持多值索引加载测试，能够以较低的成本满足用户的查询需求。\\n\\n功能丰富\\n问天引擎支持多种分析器类 型、多种索引类型、强大的查询语法，能够很好的满足用户的检索需求。同时我们还提供插件机制，方便用户定制自己的业务处理逻辑。\\n\\nSQL查询\\n问天引擎支持SQL查询语法，支持多表在线join，提供丰富的内置UDF函数和UDF函数定制机制，以满足不同用户的检索需求。在运维系统中我们即将集成SQL studio，方便用户进行SQL开发和测试。",
				"meta": {
					"parent_id": "dee776dda3ff4b078bccf989a6bda9c6",
					"id": "26ab0e4f7665487bb0a82c5a226ac1b6",
					"type": "text"
				}
			}
		],
		"nodes": [
			{
				"id": "dee776dda3ff4b078bccf989a6bda9c6",
				"type": "root",
				"parent_id": "dee776dda3ff4b078bccf989a6bda9c6"
			},
			{
				"id": "27eea7c6b2874cb7a5bf6c71afbfa32e",
				"type": "sentence",
				"parent_id": "dee776dda3ff4b078bccf989a6bda9c6"
			},
			{
				"id": "bf9fcfb47fcf410aa05216e268df2b2d",
				"type": "sentence",
				"parent_id": "dee776dda3ff4b078bccf989a6bda9c6"
			},
			{
				"id": "26ab0e4f7665487bb0a82c5a226ac1b6",
				"type": "sentence",
				"parent_id": "dee776dda3ff4b078bccf989a6bda9c6"
			}
		],
		"rich_texts": []
	}
}

异常响应示例

在访问请求出错的情况下，输出的结果中会通过 code 和 message 指明出错原因。

{
    "request_id": "817964CD-1B84-4AE1-9B63-4FB99734DD41",
    "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]"
}

状态码说明

更多状态码说明，请参考：状态码说明。