AI Search Open Platform ofrece un servicio de segmentación de documentos accesible mediante una API. Puede integrar este servicio en sus flujos de trabajo empresariales para mejorar la eficiencia de recuperación y procesamiento.
|
Nombre del servicio |
ID del servicio |
Descripción |
Límite de QPS de la API |
|
Document Chunking Service-001 |
ops-document-split-001 |
Proporciona estrategias generales de segmentación de texto para dividir datos estructurados en formatos HTML, Markdown y texto sin formato, basándose en el formato de párrafos, la semántica del texto o reglas específicas. También permite extraer bloques de código, imágenes y tablas desde texto enriquecido. |
2 Nota
Para solicitar un límite mayor de QPS de la API, envíe un ticket al soporte técnico. |
En los pipelines de generación aumentada por recuperación (RAG), normalmente se convierten los documentos en vectores y se almacenan en una base de datos vectorial para su posterior recuperación. El servicio de segmentación de documentos divide los documentos extensos en fragmentos más pequeños que cumplen con los requisitos de longitud de los modelos de embedding de texto. Este proceso le permite vectorizar y recuperar contenido de documentos muy largos.
Uso básico
La API de segmentación recibe como entrada una cadena de texto sin formato y opciones de configuración adicionales, y devuelve el texto segmentado junto con posibles elementos de texto enriquecido. La respuesta de la API contiene cuatro listas: chunks, nodes, rich_texts y sentences. Para el paso posterior de embedding, extraiga el contenido de la lista chunks y de los elementos de la lista rich_texts cuyo tipo no sea image. Consulte la plantilla de código disponible en el centro de escenarios. El siguiente código en Python es un ejemplo:
# 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})
Uso avanzado
El servicio de segmentación de documentos puede dividir documentos complejos en fragmentos según un límite de tokens especificado, lo que genera una estructura de árbol de múltiples nodos. Durante la fase de recuperación en un pipeline RAG, esta estructura arbórea permite agregar contexto a los fragmentos recuperados y así mejorar la precisión de la respuesta final.
La lógica del servicio divide el texto en el nivel estructural más alto posible. Si un fragmento resultante excede la longitud especificada, el servicio lo divide recursivamente hasta que todos los fragmentos cumplan con el requisito de longitud. Este proceso recursivo forma un árbol de fragmentos, donde cada nodo hoja corresponde a un resultado final de fragmentación, también conocido como nodo final.
En el proceso subsiguiente de recuperación vectorial, puede utilizar la información del árbol de fragmentos para completar el contexto. Por ejemplo, dentro del límite de tokens de su modelo, incluya fragmentos hermanos del mismo nivel que el fragmento recuperado para que la información contextual sea más completa.
Por ejemplo, dado el siguiente texto:
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.
Un posible árbol de fragmentos es el siguiente:
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.]
Dado un tamaño máximo de fragmento, el árbol completo contiene dos tipos de nodos: nodos finales (nodos con contenido de fragmento) y nodos intermedios (nodos lógicos sin contenido). El servicio devuelve todo el árbol como una lista de todos los nodos (nodes) y los nodos finales en una lista separada (chunks). A continuación se describen algunos tipos posibles de nodos:
root: el nodo raíz.
paragraph_node: un nodo de párrafo que representa una división basada en el delimitador
"\n\n"e identifica la posición de un párrafo. Dado que el ejemplo no contiene"\n\n", solo existe uno de estos nodos intermedios.newline_node: un nodo de nueva línea que representa una división basada en el delimitador
"\n". En el ejemplo, elnewline_node (ef4d)cumple con el requisito de tamaño de fragmento y, por lo tanto, es un nodo final; mientras que elnewline_node (c618)requiere una división adicional y es un nodo intermedio.sentence_node: un nodo de oración que representa una división basada en un delimitador de oración, como un punto (
.).subsentence_node: un nodo de suboración que representa una división basada en un delimitador de cláusula, como una coma (
,). Este tipo no aparece en el ejemplo.
Para contenido proporcionado en formato Markdown o HTML, el servicio también extrae elementos de texto enriquecido en una lista rich_texts independiente. Algunos ejemplos de estos elementos incluyen las etiquetas <img>, <table> y <code>. En el texto segmentado, el servicio reemplaza las posiciones de estos elementos con marcadores de posición como [image_0], <table>table_0</table> y <code>code_0</code>. Este diseño permite la recuperación independiente de bloques de texto enriquecido y facilita su reinserción en el contexto original cuando sea necesario. Cada bloque de texto enriquecido pertenece a un único fragmento de nodo final.
Además, para mejorar las tasas de recuperación en consultas cortas, establezca el parámetro strategy.need_sentence en true. Esto indica al servicio que divida el texto original por oraciones y devuelva los resultados en una lista sentences separada, la cual puede usarse como una ruta de recuperación independiente. Para facilitar la extensión de oraciones, cada bloque de oración pertenece a un único fragmento de nodo final. Tenga en cuenta que esta lista sentences no está relacionada con el tipo sentence_node descrito anteriormente.
Los campos en negrita mencionados anteriormente —chunks, nodes, rich_texts y sentences— son los campos que devuelve la API. Encontrará información detallada sobre su uso en las descripciones de parámetros que se presentan a continuación. Para simplificar, la salida de cada fragmento utiliza una sintaxis HTML simplificada.
Requisitos previos
-
Obtenga las credenciales de autenticación
La plataforma abierta AI Search requiere una clave de API para la autenticación. Para obtener instrucciones, consulte Get an API key.
-
Obtenga el endpoint del servicio
Puede invocar el servicio a través de la red pública o de una VPC. Para más detalles, consulte Get the service endpoint.
Especificaciones de la solicitud
Notas generales
El tamaño máximo del cuerpo de la solicitud es de 8 MB.
Método de solicitud
POST
URL
{host}/v3/openapi/workspaces/{workspace_name}/document-split/{service_id}
host: el endpoint del servicio. Puede invocar el servicio a través de Internet o mediante una VPC. Para más información, consulte Obtain service endpoints. El marcador de posición{host}corresponde a la dirección del endpoint de la API. Puede obtenerla en la página API key Management, ubicada en el panel de navegación izquierdo de AI Search Development Workbench. La sección API Endpoint proporciona dominios de API públicos para acceso por Internet y dominios de API internos para acceso desde una VPC en la misma región. Ambos dominios admiten HTTPS.workspace_name: el nombre del espacio de trabajo. Por ejemplo,default.service_id: el ID del servicio integrado. Por ejemplo,ops-document-split-001.
Parámetros de solicitud
Parámetros de encabezado
Autenticación mediante clave de API
|
Parámetro |
Tipo |
Obligatorio |
Descripción |
Ejemplo |
|
Content-Type |
String |
Sí |
El tipo de solicitud: |
application/json |
|
Authorization |
String |
Sí |
La clave de API. |
Bearer OS-d1**2a |
Parámetros del cuerpo
|
Parámetro |
Tipo |
Obligatorio |
Descripción |
Ejemplo |
|
document.content |
String |
Sí |
El contenido de texto sin formato que se va a segmentar. Según el estándar JSON, los siguientes caracteres especiales en un campo de cadena deben escaparse: |
"Title\nFirst line\nSecond line" |
|
document.content_encoding |
String |
No |
La codificación de caracteres del contenido.
|
utf8 |
|
document.content_type |
String |
No |
El formato del contenido.
|
html |
|
strategy.type |
String |
No |
La estrategia de segmentación por párrafos.
|
default |
|
strategy.max_chunk_size |
Int |
No |
La longitud máxima del fragmento. Valor predeterminado: 300. |
300 |
|
strategy.compute_type |
String |
No |
El método para calcular la longitud del fragmento.
|
token |
|
strategy.need_sentence |
Boolean |
No |
Especifica si también se devuelven fragmentos a nivel de oración para optimizar las búsquedas de consultas cortas.
|
false |
|
strategy.custom_split_label |
String |
No |
Cadenas de división personalizadas. Cuando este parámetro no está vacío, solo se utilizan las cadenas personalizadas para la división y se ignora la estrategia predeterminada. Se pueden especificar varias cadenas de división personalizadas, separadas por comas (
|
|
Información adicional:
El parámetro
strategy.need_sentence: la segmentación a nivel de oración es una estrategia independiente de la segmentación a nivel de párrafo. Cada oración se devuelve como un fragmento individual. Cuando se habilita la segmentación a nivel de oración, pueden recuperarse simultáneamente fragmentos cortos (oraciones) y largos (párrafos), los cuales se complementan entre sí para mejorar la tasa general de recuperación.
Parámetros de respuesta
|
Parámetro |
Tipo |
Descripción |
Ejemplo |
|
request_id |
String |
El ID único que el sistema asigna a la llamada de API. |
B4AB89C8-B135-****-A6F8-2BAB801A2CE4 |
|
latency |
Float/Int |
El tiempo empleado para procesar la solicitud, en milisegundos (ms). |
10 |
|
usage |
Object |
Información de facturación de la llamada. |
"usage": { "token_count": 3072 } |
|
usage.token_count |
Int |
El número de tokens. |
3072 |
|
result.chunks |
List(Chunk) |
Una lista de resultados de segmentación (nodos finales) que contiene el contenido del fragmento y sus metadatos. |
[{ "content" : "xxx", "meta":{'parent_id':x, 'id': x, 'type': 'text'} }] |
|
result.chunks[].content |
String |
El contenido del fragmento. |
"xxx" |
|
result.chunks[].meta |
Map |
Metadatos del fragmento. Todos los siguientes campos son de tipo cadena:
|
{ 'parent_id': '3b94a18555c44b67b193c6ab4f****', 'id': 'c9edcb38fdf34add90d62f6bf5c6****, 'type': 'text' 'token': 10, } |
|
result.rich_texts |
List(RichText) |
Salida de texto enriquecido. Cuando Nota
Este formato no es compatible cuando |
[{ "content" : "xxx", "meta":{'belonged_chunk_id':x, 'id': x, 'type': 'table'} }] |
|
result.rich_texts[].content |
String |
El contenido del fragmento de texto enriquecido. El |
"<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 |
Metadatos del fragmento de texto enriquecido. Todos los siguientes campos son de tipo cadena:
|
{ 'type': 'table', 'belonged_chunk_id': 'f0254cb7a5144a1fb3e5e024a3****b', 'id': 'table_2-1' 'token': 10 } |
|
result.nodes |
List(Node) |
Una lista de todos los nodos en el árbol de fragmentos. |
[{'parent_id':x, 'id': x, 'type': 'text'}] |
|
result.nodes[] |
Map |
Información sobre un nodo en el árbol de fragmentos. Todos los siguientes campos son de tipo cadena:
|
{ 'id': 'f0254cb7a5144a1fb3e5e024a3****b', 'type': 'paragraph_node', 'parent_id': 'f0254cb7a5144a1fb3e5e024a3****b' } |
|
result.sentences (opcional) |
List(sentence) |
Se devuelve una lista de oraciones de cada fragmento solo cuando |
[{ "content" : "xxx", "meta":{'belonged_chunk_id':x, 'id': x, 'type': 'sentence'} }] |
|
result.sentences[].content (opcional) |
String |
El contenido de la oración. |
"123" |
|
result.sentences[].meta (opcional) |
Map |
Metadatos de la oración:
|
{ 'id': 'f0254cb7a5144a1fb3e5e024a3****b1-1', 'type': 'sentence', 'belonged_chunk_id': 'f0254cb7a5144a1fb3e5e024a3****b', 'token': 10 } |
Ejemplo de solicitud cURL
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
}
}"
Ejemplos de respuesta
Respuesta correcta
{
"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": []
}
}
Respuesta de error
Si ocurre un error, la respuesta incluye los campos code y message que indican la causa.
{
"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]"
}
Códigos de estado
Para más información, consulte Status codes para AI Search Open Platform.