AI Search Open Platform は、 API 経由で呼び出せるドキュメントチャンキングサービスを提供します。このサービスをビジネスワークフローに統合することで、取得と処理の効率を向上させることができます。
|
サービス名 |
サービス ID |
説明 |
API QPS 制限 |
|
ドキュメントチャンキングサービス-001 |
ops-document-split-001 |
HTML、Markdown、およびプレーンテキスト形式のドキュメントに含まれる構造化データを、段落の書式設定、テキストセマンティクス、または指定されたルールに基づいて分割する、一般的なテキストチャンキング戦略を提供します。また、リッチテキストからコードブロック、画像、およびテーブルを抽出する機能もサポートします。 |
2 説明
より高い API QPS 制限をリクエストするには、テクニカルサポートにチケットを送信してください。 |
検索拡張生成 (RAG) パイプラインでは、通常、ドキュメントをベクトルに変換し、検索のためにベクトルデータベースに格納します。ドキュメントチャンキングサービスは、長いドキュメントをテキスト埋め込みモデルの長さ要件を満たす小さなチャンクに分割します。このプロセスにより、非常に長いドキュメントからコンテンツをベクトル化して取得できるようになります。
基本的な使い方
チャンキング API は、プレーンテキストの文字列と追加の設定オプションを入力として受け取り、チャンク化されたテキストと、場合によってはリッチテキスト要素を返します。API レスポンスには、chunks、nodes、rich_texts、および sentences の 4 つのリストが含まれます。次のエンベディングステップでは、chunks リストと、rich_texts リスト内でタイプが image ではない項目からコンテンツを抽出してください。シナリオセンターのコードテンプレートを参照できます。以下に Python コードの例を示します:
# チャンキング結果を抽出します。ここでは ["chunks"] と ["rich_texts"] (画像を除く) のみを使用します。
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})
応用
ドキュメントチャンキングサービスは、指定されたトークン制限に基づいて複雑なドキュメントをチャンクに分割し、マルチノードツリー構造を作成します。RAG パイプラインの取得フェーズでこのツリー構造を使用すると、取得されたチャンクにコンテキストを追加して、最終的な応答の精度を向上させることができます。
サービスは、可能な限り最上位の構造レベルでテキストを分割します。分割後のチャンクが指定した長さを超える場合、サービスは、すべてのチャンクが長さ要件を満たすまで再帰的に分割を繰り返します。この再帰的なプロセスによりチャンクツリーが形成され、各リーフノード (最終ノードとも呼ばれます) は最終的なチャンク結果に対応します。
後続のベクトルリコールプロセスでは、チャンクツリーからの情報をコンテキスト補完に使用できます。たとえば、モデルのトークン制限内で、リコールされたチャンクと同じレベルの兄弟チャンクを含めることで、コンテキスト情報を拡充できます。
例えば、以下のテキストがあるとします。
AI Search Open Platform サービスを初めて正常に有効にすると、システムによってデフォルトのワークスペースである Default が自動的に作成されます。
[ワークスペースの作成] をクリックし、カスタムワークスペース名を入力して [確認] をクリックします。[新しい API キーの作成] をクリックすると、システムによって API キーが生成されます。その後、[コピー] ボタンをクリックして API キーをコピーし、保存できます。
考えられるチャンクツリーの一例は以下の通りです:
root (6b15)
|
+-- paragraph_node (557b)
|
+-- newline_node (ef4d)[AI Search Open Platform を正常に有効にした後...デフォルト。]
|
+-- newline_node (c618)
|
+-- sentence_node (98ce)[ワークスペースの作成をクリックし...次に確認をクリックします。]
|
+-- sentence_node (922a)[新しい API キーの作成をクリックした後...API キーをコピーして保存します。]
最大チャンクサイズが指定されている場合、完全なチャンクツリーには、最終ノード (チャンクコンテンツを持つノード) と中間ノード (コンテンツを持たない論理ノード) の 2 種類のノードが含まれます。サービスは、ツリー全体をすべてのノードのリスト (nodes) として、最終ノードを別のリスト (chunks) として返します。考えられるノードタイプは以下の通りです:
-
root : ルートノードです。
-
paragraph_node :
"\n\n"区切り文字に基づく分割を表し、パラグラフの位置を識別するパラグラフノードです。この例には"\n\n"が含まれていないため、このような中間ノードは 1 つのみです。 -
newline_node :
"\n"区切り文字に基づく分割を表す改行ノードです。この例では、newline_node (ef4d)はチャンクサイズの要件を満たしているため最終ノードですが、newline_node (c618)はさらに分割が必要なため中間ノードです。 -
sentence_node : ピリオド (
.) などの文の区切り文字に基づく分割を表す文ノードです。 -
subsentence_node : カンマ (
,) などの句の区切り文字に基づく分割を表すサブセンテンスノードです。このタイプはこの例には含まれていません。
Markdown または HTML フォーマットのコンテンツでは、サービスはリッチテキスト要素も別の rich_texts リストに抽出します。こうした要素の例として、<img>、<table>、<code> タグがあります。チャンク化されたテキストでは、サービスはこれらの要素の位置を [image_0]、<table>table_0</table>、<code>code_0</code> のようなプレースホルダーに置き換えます。この設計により、リッチテキスト ブロックを個別に呼び出し、必要に応じて元のコンテキストに再挿入できます。各リッチテキスト ブロックは、一意の最終ノード チャンクに属します。
さらに、短いクエリの再現率を向上させるために、strategy.need_sentence パラメーターを true に設定できます。これにより、サービスは元のテキストをセンテンス単位で分割し、結果を別の sentences リストで返します。このリストは、独立した取得パスとして使用できます。センテンスの拡張を容易にするため、各センテンス ブロックは一意の最終ノード チャンクに属します。なお、この sentences リストは、前述の sentence_node タイプとは関連がありません。
上記の太字で示した chunks、nodes、rich_texts、sentences は、API によって返されるフィールドです。詳細な使用方法については、以降のパラメーターの説明をご参照ください。簡略化のため、各チャンクの出力には簡易 HTML 構文が使用されます。
前提条件
-
認証情報の取得
AI Search オープンプラットフォームでは、認証に API キーが必要です。手順については、「API キーの取得」をご参照ください。
-
サービスエンドポイントの取得
パブリックネットワークまたは VPC 経由でサービスを呼び出せます。詳細については、「サービスエンドポイントの取得」をご参照ください。
リクエスト仕様
一般的な注意事項
-
リクエストボディの最大サイズは 8 MB です。
リクエストメソッド
POST
URL
{host}/v3/openapi/workspaces/{workspace_name}/document-split/{service_id}
-
host:サービスのエンドポイントです。サービスはインターネット経由または VPC 経由で呼び出すことができます。詳細については、「サービスエンドポイントの取得」をご参照ください。{host}プレースホルダーは API のエンドポイントアドレスです。AI Search Development Workbench の左側のナビゲーションペインにある API キー管理 ページから取得できます。API エンドポイント セクションには、インターネットアクセス用のパブリック API ドメインと、同じリージョン内の VPC からアクセスするための内部 API ドメインが用意されています。どちらのドメインも HTTPS に対応しています。 -
workspace_name:ワークスペースの名前です。例:default -
service_id:組み込みサービス ID です。例:ops-document-split-001
リクエストパラメータ
ヘッダー パラメーター
API キー認証
|
パラメーター |
型 |
必須 |
説明 |
例 |
|
Content-Type |
文字列 |
はい |
リクエストタイプ: |
application/json |
|
Authorization |
文字列 |
はい |
API キー。 |
Bearer OS-d1**2a |
ボディ パラメーター
|
パラメーター |
タイプ |
必須 |
説明 |
例 |
|
document.content |
文字列 |
はい |
チャンク化するプレーンテキストのコンテンツです。JSON 標準によれば、文字列フィールド内の次の特殊文字はエスケープする必要があります: |
"Title\nFirst line\nSecond line" |
|
document.content_encoding |
文字列 |
いいえ |
コンテンツの文字エンコーディングです。
|
utf8 |
|
document.content_type |
文字列 |
いいえ |
コンテンツのフォーマットです。
|
html |
|
strategy.type |
文字列 |
いいえ |
段落チャンキング戦略です。
|
default |
|
strategy.max_chunk_size |
整数 |
いいえ |
最大チャンク長です。デフォルト値: 300。 |
300 |
|
strategy.compute_type |
文字列 |
いいえ |
チャンク長の計算方法です。
|
token |
|
strategy.need_sentence |
ブール値 |
いいえ |
短いクエリの検索を最適化するために、文レベルのチャンクも返すかどうかを指定します。
|
false |
|
strategy.custom_split_label |
文字列 |
いいえ |
カスタム分割文字列。このパラメーターが空でない場合、カスタム文字列のみを分割に使用し、デフォルトの戦略は無視します。複数のカスタム分割文字列は、カンマ (
|
|
追加情報:
-
strategy.need_sentenceパラメーター:文レベルのチャンキングは、段落レベルのチャンキングとは独立した戦略です。各文を個別のチャンクとして返します。文レベルのチャンキングを有効にすると、短い (文) チャンクと長い (段落) チャンクを同時に取得でき、相互に補完することで全体の再現率が向上します。
レスポンスパラメーター
|
パラメーター |
タイプ |
説明 |
例 |
|
request_id |
文字列 |
システムが API 呼び出しに割り当てる一意の ID です。 |
B4AB89C8-B135-****-A6F8-2BAB801A2CE4 |
|
latency |
フロート/整数 |
リクエストの処理にかかった時間です (単位:ミリ秒)。 |
10 |
|
usage |
オブジェクト |
呼び出しの請求情報です。 |
"usage": { "token_count": 3072 } |
|
usage.token_count |
整数 |
トークン数です。 |
3072 |
|
result.chunks |
リスト (チャンク) |
チャンキング結果 (最終ノード) のリストです。チャンクのコンテンツとメタデータが含まれます。 |
[{ "content" : "xxx", "meta":{'parent_id':x, 'id': x, 'type': 'text'} }] |
|
result.chunks[].content |
文字列 |
チャンクのコンテンツです。 |
"xxx" |
|
result.chunks[].meta |
マップ |
チャンクのメタデータです。以下のすべてのフィールドは文字列型です。
|
{ 'parent_id': '3b94a18555c44b67b193c6ab4f****', 'id': 'c9edcb38fdf34add90d62f6bf5c6****, 'type': 'text' 'token': 10, } |
|
result.rich_texts |
リスト (リッチテキスト) |
リッチテキストの出力です。 説明
|
[{ "content" : "xxx", "meta":{'belonged_chunk_id':x, 'id': x, 'type': 'table'} }] |
|
result.rich_texts[].content |
文字列 |
リッチテキストチャンクのコンテンツ。画像の |
"<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 |
マップ |
リッチテキストチャンクのメタデータです。以下のすべてのフィールドは文字列型です。
|
{ 'type': 'table', 'belonged_chunk_id': 'f0254cb7a5144a1fb3e5e024a3****b', 'id': 'table_2-1' 'token': 10 } |
|
result.nodes |
リスト (ノード) |
チャンクツリー内のすべてのノードのリストです。 |
[{'parent_id':x, 'id': x, 'type': 'text'}] |
|
result.nodes[] |
マップ |
チャンクツリー内のノードに関する情報です。以下のすべてのフィールドは文字列型です。
|
{ 'id': 'f0254cb7a5144a1fb3e5e024a3****b', 'type': 'paragraph_node', 'parent_id': 'f0254cb7a5144a1fb3e5e024a3****b' } |
|
result.sentences (オプション) |
リスト (文) |
各チャンクの文のリストが、リクエストの |
[{ "content" : "xxx", "meta":{'belonged_chunk_id':x, 'id': x, 'type': 'sentence'} }] |
|
result.sentences[].content (オプション) |
文字列 |
文のコンテンツです。 |
"123" |
|
result.sentences[].meta (オプション) |
マップ |
文のメタデータです。
|
{ 'id': 'f0254cb7a5144a1fb3e5e024a3****b1-1', 'type': 'sentence', 'belonged_chunk_id': 'f0254cb7a5144a1fb3e5e024a3****b', 'token': 10 } |
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\":\"製品のメリット\\nIndustry Algorithm Edition\\nインテリジェント\\n豊富なカスタマイズ可能なアルゴリズムモデルと業界特化の再現率およびランキングアルゴリズムを備え、優れた検索結果を実現します。\\n\\n柔軟かつカスタマイズ可能\\n開発者は、ビジネス特性とデータに基づいて、アルゴリズムモデル、アプリケーション構造、データ処理、クエリ分析、ランキング設定をカスタマイズできます。これにより、パーソナライズされた検索ニーズに対応し、クリックスルー率を向上させ、迅速なビジネスイテレーションを可能にし、新機能の市場投入までの時間を大幅に短縮します。\\n\\nセキュアで安定\\nオンラインチケットおよび電話サポートにより24時間365日の運用保守とテクニカルサポートを提供します。包括的なインシデント対応メカニズムには、障害モニタリング、自動アラート、問題の迅速な特定が含まれます。Alibaba Cloud AccessKeyId と AccessKeySecret のセキュリティペアを使用して API レベルでアクセス制御と分離を適用し、ユーザーレベルのデータ分離とセキュリティを確保します。データは損失を防ぐために冗長バックアップされます。\\n\\n弾性スケーリング\\n必要に応じてリソースを柔軟にスケールアップまたはスケールダウンできます。\\n\\n周辺機能が豊富\\nホットサーチ、検索サジェスト、統計レポートなど、表示と分析に便利な各種の周辺検索機能をサポートします。\\n\\nすぐに使える\\nクラスターをデプロイまたは保守する必要はありません。ワンストップの検索サービスに迅速にアクセスできます。\\n\\nHigh-Performance Retrieval Edition\\n高スループット\\n単一テーブルで数万の書き込み TPS をサポートし、更新は数秒で反映されます。\\n\\nセキュアで安定\\nオンラインチケットおよび電話サポートにより24時間365日の運用保守とテクニカルサポートを提供します。包括的なインシデント対応メカニズムには、障害モニタリング、自動アラート、問題の迅速な特定が含まれます。Alibaba Cloud AccessKeyId と AccessKeySecret のセキュリティペアを使用して API レvelでアクセス制御と分離を適用し、ユーザーレベルのデータ分離とセキュリティを確保します。データは損失を防ぐために冗長バックアップされます。\\n\\n弾性スケーリング\\n必要に応じてリソースを柔軟にスケールアップまたはスケールダウンできます。\\n\\nすぐに使える\\nクラスターをデプロイまたは保守する必要はありません。ワンストップの検索サービスに迅速にアクセスできます。\\n\\nVector Retrieval Edition\\n安定\\n基盤実装は C++ で 10 年以上にわたり開発され、複数のコアビジネスを支えてきました。高い安定性を備え、ミッションクリティカルな検索シナリオに適しています。\\n\\n効率的\\n大規模なデータ取得とリアルタイムデータ更新 (数秒で反映) を効率的にサポートする分散検索エンジンであり、クエリレイテンシーと適時性が重視される検索シナリオに最適です。\\n\\n費用対効果が高い\\n複数のインデックス圧縮戦略とマルチバリューインデックスのロードテストをサポートし、より低コストでユーザーのクエリ要件を満たします。\\n\\nベクターアルゴリズム\\n音声、画像、動画、テキスト、行動などの各種非構造化データに対するベクトル検索をサポートします。\\n\\nSQL クエリ\\nSQL 構文およびオンラインでのマルチテーブル結合をサポートします。多様な取得ニーズに対応するため、豊富な組み込み UDF と UDF カスタマイズメカニズムを提供します。SQL Studio は運用システムに統合されており、SQL の開発とテストを容易に行えます。\\n\\nRecall Engine Edition\\n安定\\n基盤実装は C++ で 10 年以上にわたり開発され、複数のコアビジネスを支えてきました。高い安定性を備え、ミッションクリティカルな検索シナリオに適しています。\\n\\n効率的\\nWentian Engine は分散検索エンジンであり、大規模なデータ取得とリアルタイムデータ更新 (数秒で反映) を効率的にサポートします。クエリレイテンシーと適時性が重視される検索シナリオに最適です。\\n\\n費用対効果が高い\\nWentian Engine は複数のインデックス圧縮戦略とマルチバリューインデックスのロードテストをサポートし、より低コストでユーザーのクエリ要件を満たします。\\n\\n機能が豊富\\nWentian Engine は各種アナライザータイプ、インデックスタイプ、強力なクエリ構文をサポートし、ユーザーの取得ニーズに対応します。ビジネスロジックをカスタマイズするためのプラグインメカニズムも提供しています。\\n\\nSQL クエリ\\nWentian Engine は SQL 構文およびオンラインでのマルチテーブル結合をサポートします。多様な取得ニーズに対応するため、豊富な組み込み 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-****-448C-A1D5-50B89D7EA434",
"latency": 161,
"usage": {
"token_count": 800
},
"result": {
"chunks": [
{
"content": "製品の利点\n\nIndustry Algorithm Edition\n\nインテリジェント\nカスタマイズ可能な豊富なアルゴリズムモデルと、業界固有のリコールおよびランキングアルゴリズムを備え、優れた検索結果を保証します。\n\n柔軟性とカスタマイズ性\n開発者は、ビジネスの特性やデータに基づいて、アルゴリズムモデル、アプリケーション構造、データ処理、クエリアナリシス、ランキング設定をカスタマイズできます。これにより、パーソナライズされた検索ニーズに対応し、クリックスルー率を向上させ、迅速なビジネスイテレーションを実現し、新機能のタイムトゥマーケットを大幅に短縮します。\n\n安全性と安定性\nオンラインチケットと電話サポートを通じて、24 時間 365 日の運用保守とテクニカルサポートを提供します。包括的なインシデント対応メカニズムには、障害モニタリング、自動アラート、迅速な問題の特定が含まれます。Alibaba Cloud の AccessKeyId と AccessKeySecret のセキュリティペアを使用することで、API レベルでのアクセス制御と隔離を強制し、ユーザーレベルのデータ分離とセキュリティを保証します。データを冗長的にバックアップし、損失を防ぎます。\n\nエラスティックスケーリング\n必要に応じて、リソースを弾性的にスケールアップまたはスケールダウンできます。\n\n豊富な周辺機能\nホットサーチ、検索サジェスト、統計レポートなど、さまざまな周辺検索機能をサポートし、表示や分析を容易にします。\n\nすぐに使える\nクラスターのデプロイやメンテナンスは不要です。ワンストップの検索サービスに迅速にアクセスできます。\n\nHigh-Performance Retrieval Edition\n\n高スループット\n単一テーブルで数万の書き込み TPS をサポートし、更新は数秒で完了します。",
"meta": {
"parent_id": "dee776dda3ff4b078bccf989a6bd****",
"id": "27eea7c6b2874cb7a5bf6c71afbf****",
"type": "text"
}
},
{
"content": "\n\n安全性と安定性\nオンラインチケットと電話サポートを通じて、24 時間 365 日の運用保守とテクニカルサポートを提供します。包括的なインシデント対応メカニズムには、障害モニタリング、自動アラート、迅速な問題の特定が含まれます。Alibaba Cloud の AccessKeyId と AccessKeySecret のセキュリティペアを使用することで、API レベルでのアクセス制御と隔離を強制し、ユーザーレベルのデータ分離とセキュリティを保証します。データを冗長的にバックアップし、損失を防ぎます。\n\nエラスティックスケーリング\n必要に応じて、リソースを弾性的にスケールアップまたはスケールダウンできます。\n\nすぐに使える\nクラスターのデプロイやメンテナンスは不要です。ワンストップの検索サービスに迅速にアクセスできます。\n\nVector Retrieval Edition\n\n安定性\nC++ での基盤実装は 10 年以上にわたって開発されており、複数のコアビジネスをサポートしているため、非常に安定しており、ミッションクリティカルな検索シナリオに適しています。\n\n効率性\n分散型検索エンジンであり、大量のデータ取得とリアルタイムのデータ更新(数秒で有効)を効率的にサポートするため、クエリレイテンシーとリアルタイム性が重要な検索シナリオに最適です。\n\nコスト効率\n複数のインデックス圧縮戦略とマルチバリューインデックスの読み込みテストをサポートし、より低いコストでユーザーのクエリニーズに応えます。\n\nベクトルアルゴリズム\n音声、画像、動画、テキスト、行動など、さまざまな非構造化データのベクトル検索をサポートします。\n\nSQL クエリ\nSQL 構文とオンラインでの複数テーブル結合をサポートします。豊富な組み込み UDF と UDF カスタマイズメカニズムを提供し、多様な取得ニーズに応えます。",
"meta": {
"parent_id": "dee776dda3ff4b078bccf989a6bd****",
"id": "bf9fcfb47fcf410aa05216e268df****",
"type": "text"
}
},
{
"content": "SQL Studio はまもなくオペレーションシステムに統合され、SQL の開発とテストが容易になります。\n\nRecall Engine Edition\n\n安定性\nC++ での基盤実装は 10 年以上にわたって開発されており、複数のコアビジネスをサポートしているため、非常に安定しており、ミッションクリティカルな検索シナリオに適しています。\n\n効率性\nWentian Engine は分散型検索エンジンであり、大量のデータ取得とリアルタイムのデータ更新(数秒で有効)を効率的にサポートするため、クエリレイテンシーとリアルタイム性が重要な検索シナリオに最適です。\n\nコスト効率\nWentian Engine は、複数のインデックス圧縮戦略とマルチバリューインデックスの読み込みテストをサポートし、より低いコストでユーザーのクエリニーズに応えます。\n\n豊富な機能\nWentian Engine は、さまざまなアナライザータイプ、インデックスタイプ、強力なクエリ構文をサポートし、ユーザーの取得ニーズに応えます。ビジネスロジックをカスタマイズするためのプラグインメカニズムも用意されています。\n\nSQL クエリ\nWentian Engine は SQL 構文とオンラインでの複数テーブル結合をサポートします。豊富な組み込み UDF と UDF カスタマイズメカニズムを提供し、多様な取得ニーズに応えます。SQL Studio はまもなくオペレーションシステムに統合され、SQL の開発とテストが容易になります。",
"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": []
}
}
エラーレスポンス
エラーが発生した場合、レスポンスには原因を示す code フィールドと message フィールドが含まれます。
{
"request_id": "817964CD-1B84-4AE1-9B63-4FB99734****",
"latency": 0,
"code": "InvalidParameter",
"message": "JSON 解析エラー: 無効な UTF-8 開始バイト 0xbc; ネストされた例外: com.fasterxml.jackson.core.JsonParseException: 無効な UTF-8 開始バイト 0xbc\n 行: 2, 列: 19]"
}
ステータスコード
詳細については、 AI Search Open Platform の「ステータスコード」をご参照ください。