PAI-RAG サービス API (v0.4.x) - Platform For AI - Alibaba Cloud ドキュメントセンター

このドキュメントでは、PAI-RAG サービスのバージョン v0.4.x について説明します。開発者が PAI-RAG の機能を迅速かつ効率的にアプリケーションに統合できるよう、API 定義、リクエスト例、およびコアコンセプトを提供します。

前提条件：エンドポイントとトークンの取得

API 経由で RAG サービスを呼び出すには、サービスのエンドポイントとトークンを取得する必要があります。すべての API リクエストには、HTTP Authorization ヘッダーに EAS_TOKEN を含める必要があります。

以下の API の説明に記載されている $EAS_SERVICE_URL と $EAS_TOKEN は環境変数です。使用する前に設定する必要があります。次の手順に従って取得してください。

PAI コンソールにログインします。ページ上部でリージョンを選択します。次に、目的のワークスペースを選択し、[Elastic Algorithm Service (EAS)] をクリックします。
対象のサービス名をクリックし、Basic Information セクションで View Endpoint Information をクリックします。
Invocation Method ページで、インターネット/VPC エンドポイント (EAS_SERVICE_URL) とトークン (EAS_TOKEN) を取得します。
重要
- EAS_SERVICE_URL の値から末尾のスラッシュ (/) を削除してください。
- クライアントがパブリックインターネットにアクセスできる場合は、インターネットエンドポイントを使用してください。
- クライアントが RAG サービスと同じ Virtual Private Cloud (VPC) 内にある場合にのみ、VPC エンドポイントを使用してください。

EAS_SERVICE_URL と EAS_TOKEN を取得したら、それらを環境変数として設定して、後続の API 呼び出しを簡素化します。

export EAS_SERVICE_URL="your_service_endpoint"
export EAS_TOKEN="your_token"

設定が完了すると、後続の curl コマンドで $EAS_SERVICE_URL と $EAS_TOKEN を使用できます。

Chat API

Chat API は、エージェントと Retrieval-Augmented Generation (RAG) をサポートするストリーミングチャットインターフェイスです。OpenAI 互換のチャットプロトコルを拡張し、ナレッジベースの取得、複数ステップの推論、ツール呼び出しなどの高度な機能を備えており、インテリジェントな会話システムや質疑応答ボットの構築に適しています。

重要

Chat API を呼び出す推奨方法は、独自のチャットアプリケーションを設定することです。たとえば、my_assistant という名前のアプリケーションを作成し、そのナレッジベースと Web 検索設定を構成できます。

POST $EAS_SERVICE_URL/v1/chat/completions

説明：チャットリクエストを送信します。model パラメーターを使用して、ナレッジベース、Web 検索、またはその他のリソースにリンクされている可能性のある、事前に設定されたチャットアプリケーションを呼び出します。

リクエストボディ (application/json)

パラメーター	タイプ	必須	説明
`model`	String	はい	チャットアプリケーションの名前。
`messages`	Array	はい	OpenAI フォーマットのメッセージのリストとしての会話履歴。
`stream`	Boolean	いいえ	応答をストリーミングモードで返すかどうかを指定します。デフォルトは `false` です。

リクエストボディの例

{
    "model": "my_assistant",
    "messages": [
        {
            "role": "user",
            "content": "What are the core features of PAI-RAG?"
        }
    ],
    "stream": true
}

レスポンスボディ

応答フォーマットは OpenAI chat.completions API と互換性があります。

OpenAI クライアントの例：

from openai import OpenAI
import os
EAS_ENDPOINT = os.getenv("EAS_SERVICE_URL")
EAS_TOKEN = os.getenv("EAS_TOKEN")
client = OpenAI(
    base_url=EAS_ENDPOINT,
    api_key=EAS_TOKEN
)
response = client.chat.completions.create(
    model="my_assistant",  # ご利用のチャットアプリケーション名に置き換えてください
    messages=[
        {"role": "user", "content": "Hello"}
    ],
    stream=True
)
for chunk in response:
    print(chunk.choices[0].delta.content)

ナレッジベース管理

ナレッジベース

新しいナレッジベースを作成し、データチャンキング、埋め込み、取得の設定を構成します。

POST $EAS_SERVICE_URL/v1/config/knowledgebases

リクエスト	curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "name": "example_kb", "description": "This is an example knowledge base.", "chunk_config": { "parser_type": "structure", "separator": "\n\n", "chunk_size": 1000, "chunk_overlap": 50 }, "embedding_model": "BAAI/bge-m3", "retrieval_config": { "retrieval_mode": "hybrid", "top_k": 5, "similarity_threshold": 0.2, "enable_rerank": true, "rerank_model": "qwen3-reranker", "vector_weight": 0.7 } }'
リクエストヘッダー
Content-Type `string` (必須) リクエストのコンテンツタイプ。このパラメーターは `application/json` に設定する必要があります。
Authorization `string` (必須) リクエストの認証トークン。EAS_TOKEN を使用します。
リクエストボディ
name `string` (必須) ナレッジベースの名前。
description `string` (任意) ナレッジベースの説明。
embedding_model `string` (必須) 埋め込みモデルの名前またはパス。ローカルモデルとリモートモデルの両方がサポートされています。
chunk_config `object` (任意) データチャンキングの設定。プロパティ parser_type `string` (任意) パーサータイプ。有効な値：`structure`、`table`、`token`、`paragraph`。 separator `string` (任意) カスタムの区切り文字。 chunk_size `int` (任意) 各チャンクの最大長 (文字数)。 chunk_overlap `int` (任意) 隣接するチャンク間の重複の長さ (文字数)。 image_caption_model `string` (任意) 画像キャプションモデル。
retrieval_config `object` (任意) 取得設定。プロパティ retrieval_mode `string` (任意) 取得モード。有効な値：`hybrid` (ハイブリッド検索) と `vector` (ベクトル検索)。 top_k `int` (任意) 返す上位ランクのチャンク数。 similarity_threshold `float` (任意) この値より類似度スコアが低い結果を除外します。 enable_rerank `bool` (任意) 取得結果をリランキングするかどうかを指定します。重要この機能を使用するには、まず PAI-RAG Web UI でリランカーモデルを設定する必要があります。 rerank_model `string` (任意) リランカーモデルの名前またはパス。 vector_weight `float` (任意) ハイブリッド検索で使用されるベクトル検索コンポーネントの重み。

レスポンス例

{
    "code": 200,
    "message": "Knowledge base created successfully.",
    "data": {
        "name": "example_kb",
        "tenant_id": "__default_tenant_id__",
        "created_at": "2026-02-27T02:35:01.121035Z",
        "description": "This is an example knowledge base.",
        "updated_at": "2026-02-27T02:35:01.121046Z",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "structure",
            "separator": "\n\n",
            "image_caption_model": null,
            "image_caption_provider_name": "openai_like",
            "table_config": {
                "concat_rows": false,
                "row_joiner": "\n",
                "header_index_max": 0,
                "format_sheet_data_to_json": false,
                "sheet_column_filters": null,
                "question_column_index": 0,
                "answer_column_index": 1
            }
        },
        "id": "a4815ee728a64e9c83a3d891dbc1c956",
        "embedding_model": "BAAI/bge-m3",
        "embedding_provider_name": "openai_like",
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 5,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker",
            "rerank_provider_name": "openai_like",
            "rerank_top_k": 5
        }
    }
}

ナレッジベースのリスト表示

現在のサービス内のナレッジベースのページ分割されたリストを取得します。

GET $EAS_SERVICE_URL/v1/config/knowledgebases?page=1&size=10

リクエスト	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases?page=1&size=10" \ --header "Authorization: Bearer $EAS_TOKE"`
リクエストヘッダー
Authorization `string` (必須) リクエストの認証トークン。EAS_TOKEN の値を使用します。
クエリパラメーター
page `int` (任意) 取得するページ番号。デフォルト値は `1` です。
size `int` (任意) ページあたりのアイテム数。デフォルト値は `10` で、最大値は `1000` です。

レスポンス例

{
    "code": 200,
    "message": "Successfully retrieved the list of knowledge bases.",
    "data": {
        "items": [
            {
                "name": "example_kb",
                "tenant_id": "__default_tenant_id__",
                "created_at": "2026-02-27T02:35:01.121035Z",
                "description": "This is an example knowledge base.",
                "updated_at": "2026-02-27T02:35:01.121046Z",
                "chunk_config": {
                    "chunk_size": 1000,
                    "chunk_overlap": 50,
                    "parser_type": "structure",
                    "separator": "\n\n",
                    "image_caption_model": null,
                    "image_caption_provider_name": "openai_like",
                    "table_config": {
                        "concat_rows": false,
                        "row_joiner": "\n",
                        "header_index_max": 0,
                        "format_sheet_data_to_json": false,
                        "sheet_column_filters": null,
                        "question_column_index": 0,
                        "answer_column_index": 1
                    }
                },
                "id": "a4815ee728a64e9c83a3d891dbc1c956",
                "embedding_model": "BAAI/bge-m3",
                "embedding_provider_name": "openai_like",
                "retrieval_config": {
                    "retrieval_mode": "hybrid",
                    "top_k": 5,
                    "similarity_threshold": 0.2,
                    "vector_weight": 0.7,
                    "enable_rerank": true,
                    "rerank_model": "qwen3-reranker",
                    "rerank_provider_name": "openai_like",
                    "rerank_top_k": 5
                },
                "file_count": 0
            },
            {
                "name": "iPhone16",
                "tenant_id": "__default_tenant_id__",
                "created_at": "2026-02-25T08:57:07.085859Z",
                "description": "",
                "updated_at": "2026-02-25T09:01:40.035292Z",
                "chunk_config": {
                    "chunk_size": 1000,
                    "chunk_overlap": 50,
                    "parser_type": "structure",
                    "separator": "\n\n",
                    "image_caption_model": null,
                    "image_caption_provider_name": "openai_like",
                    "table_config": {
                        "concat_rows": false,
                        "row_joiner": "\n",
                        "header_index_max": 0,
                        "format_sheet_data_to_json": false,
                        "sheet_column_filters": null,
                        "question_column_index": 0,
                        "answer_column_index": 1
                    }
                },
                "id": "08f6bb77fd3441099fb5b19e4f10d67b",
                "embedding_model": "BAAI/bge-m3",
                "embedding_provider_name": "openai_like",
                "retrieval_config": {
                    "retrieval_mode": "vector",
                    "top_k": 5,
                    "similarity_threshold": 0.2,
                    "vector_weight": 0.7,
                    "enable_rerank": false,
                    "rerank_model": "",
                    "rerank_provider_name": "openai_like",
                    "rerank_top_k": 5
                },
                "file_count": 2
            }
        ],
        "total": 2,
        "pages": 1,
        "page": 1,
        "size": 10
    }
}

ナレッジベースの取得

ナレッジベースの詳細を取得します。

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}

リクエスト	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
ヘッダー
Authorization `string` (必須) 認証トークン。ご利用の `EAS_TOKEN` を使用します。
パスパラメーター
kb_id `string` (必須) ナレッジベースの一意の識別子。

レスポンス例

{
    "code": 200,
    "message": "Retrieved the knowledge base successfully.",
    "data": {
        "id": "a4815ee728a64e9c83a3d891dbc1c956",
        "tenant_id": "__default_tenant_id__",
        "name": "example_kb",
        "description": "This is an example knowledge base.",
        "created_at": "2026-02-27T02:35:01.121035+00:00",
        "updated_at": "2026-02-27T02:35:01.121046+00:00",
        "embedding_model": "BAAI/bge-m3",
        "embedding_provider_name": "openai_like",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "structure",
            "separator": "\n\n",
            "image_caption_model": null,
            "image_caption_provider_name": "openai_like",
            "table_config": {
                "concat_rows": false,
                "row_joiner": "\n",
                "header_index_max": 0,
                "format_sheet_data_to_json": false,
                "sheet_column_filters": null,
                "question_column_index": 0,
                "answer_column_index": 1
            }
        },
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 5,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker",
            "rerank_provider_name": "openai_like",
            "rerank_top_k": 5
        }
    }
}

ナレッジベースの更新

既存のナレッジベースを更新します。

PUT $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}

リクエスト	curl -X PUT "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "name": "example_kb", "description": "Example", "id": "kb4451867a6d0f4166babddb7a048a311d", "embedding_model": "BAAI/bge-m3", "chunk_config": { "chunk_size": 1000, "chunk_overlap": 50, "parser_type": "structure", "separator": "\n\n" }, "retrieval_config": { "retrieval_mode": "hybrid", "top_k": 6, "similarity_threshold": 0.2, "vector_weight": 0.7, "enable_rerank": true, "rerank_model": "qwen3-reranker" } }'
リクエストヘッダー
Content-Type `string` (必須) このパラメーターは `application/json` に設定する必要があります。
Authorization `string` (必須) 認証トークン。EAS_TOKEN を使用します。
パスパラメーター
kb_id `string` (必須) ナレッジベースの一意の識別子。
リクエストボディ
リクエストボディは、ナレッジベースを作成する操作と同じパラメーター (name、description、embedding_model、chunk_config、retrieval_config) を受け入れます。

レスポンス例

{
    "code": 200,
    "message": "Knowledge base updated successfully.",
    "data": {
        "name": "example_kb",
        "tenant_id": "__default_tenant_id__",
        "created_at": "2026-02-27T02:35:01.121035Z",
        "description": "Example",
        "updated_at": "2026-02-27T07:26:55.543217Z",
        "chunk_config": {
            "chunk_size": 1000,
            "chunk_overlap": 50,
            "parser_type": "structure",
            "separator": "\n\n",
            "image_caption_model": null,
            "image_caption_provider_name": "openai_like",
            "table_config": {
                "concat_rows": false,
                "row_joiner": "\n",
                "header_index_max": 0,
                "format_sheet_data_to_json": false,
                "sheet_column_filters": null,
                "question_column_index": 0,
                "answer_column_index": 1
            }
        },
        "id": "a4815ee728a64e9c83a3d891dbc1c956",
        "embedding_model": "BAAI/bge-m3",
        "embedding_provider_name": "openai_like",
        "retrieval_config": {
            "retrieval_mode": "hybrid",
            "top_k": 6,
            "similarity_threshold": 0.2,
            "vector_weight": 0.7,
            "enable_rerank": true,
            "rerank_model": "qwen3-reranker",
            "rerank_provider_name": "openai_like",
            "rerank_top_k": 5
        }
    }
}

ナレッジベースの削除

指定されたナレッジベースとそのすべてのファイルおよびインデックスを完全に削除します。この操作は元に戻すことができません。注意して実行してください。

DELETE $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}

リクエスト	`curl -X DELETE "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
リクエストヘッダー
Authorization `string` (必須) リクエストの認証トークン。EAS_TOKEN を使用します。
パスパラメーター
kb_id `string` (必須) ナレッジベースの一意の識別子。

レスポンス例

{"code":200,"message":"Knowledge base deleted successfully.","data":null}

ファイル管理

ファイルのアップロード

指定されたナレッジベースに 1 つ以上のファイルをアップロードします。この非同期 API はすぐにファイル情報を返します。解析とインデックス作成はバックグラウンドで行われます。サポートされているファイル形式は、PDF、DOCX、TXT です。

POST $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files

リクエスト	`curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: multipart/form-data' \ --form 'files=@"/path/to/your/file.pdf"'`
リクエストヘッダー
Content-Type `string` (必須) リクエストのコンテンツタイプ。このパラメーターは `multipart/form-data` に設定する必要があります。
Authorization `string` (必須) リクエストの認証トークン。ご利用の EAS_TOKEN を使用します。
パスパラメーター
kb_id `string` (必須) ナレッジベースの一意の識別子。
リクエストボディ
files `file` (必須) アップロードする 1 つ以上のファイル。

レスポンス例

{
    "code": 200,
    "message": "File upload successful",
    "data": [
        {
            "file_content_length": 0,
            "status": "pending",
            "file_source": null,
            "failed_reason": null,
            "file_name": "EAS_model_service_overview.pdf",
            "active": true,
            "tenant_id": "__default_tenant_id__",
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
            "created_at": "2026-02-27T07:30:10.875488Z",
            "id": "2540b5414f2d422291cea3162eb8e1e0",
            "file_extension": ".pdf",
            "updated_at": "2026-02-27T07:30:10.875503Z",
            "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
            "file_size": 889027,
            "file_metadata": {
                "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
                "file_name": "EAS_model_service_overview.pdf",
                "file_size": 889027,
                "file_extension": ".pdf"
            },
            "message_id": "tmp-1772177410",
            "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
            "chunk_config": {
                "chunk_size": 1000,
                "chunk_overlap": 50,
                "parser_type": "structure",
                "separator": "\n\n",
                "image_caption_model": null,
                "image_caption_provider_name": "openai_like",
                "table_config": {
                    "concat_rows": false,
                    "row_joiner": "\n",
                    "header_index_max": 0,
                    "format_sheet_data_to_json": false,
                    "sheet_column_filters": null,
                    "question_column_index": 0,
                    "answer_column_index": 1
                }
            },
            "file_content": "",
            "file_version": 1772177410
        }
    ]
}

ファイルのリスト表示

指定されたナレッジベースからファイルのページ分割されたリストを取得します。ファイル名と処理ステータスで結果をフィルタリングできます。

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files

リクエスト	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files?query=EAS&status=succeeded&page=1&size=10" \ --header "Authorization: Bearer $EAS_TOKEN"`
リクエストヘッダー
Authorization `string` (必須) 認証トークン。$EAS_TOKEN の値を使用します。
パスパラメーター
kb_id `string` (必須) ナレッジベースの ID。
クエリパラメーター
query `string` (任意) ファイル名のあいまい一致のための検索キーワード。
status `string` (任意) 処理ステータスでファイルをフィルタリングします。省略した場合、API はすべてのステータスのファイルを返します。有効な値：`pending`、`succeeded`、`failed`、`persisting`、`parsing`。
page `int` (任意) ページ番号。デフォルトは 1 です。
size `int` (任意) ページごとに返す結果の数。デフォルトは 10 です。

レスポンス例

{
    "code": 200,
    "message": "Successfully retrieved the file list.",
    "data": {
        "items": [
            {
                "file_content_length": 0,
                "status": "succeeded",
                "file_source": null,
                "failed_reason": null,
                "file_name": "EAS model service overview.pdf",
                "active": true,
                "tenant_id": "__default_tenant_id__",
                "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS model service overview.pdf",
                "created_at": "2026-02-27T07:30:10.875488Z",
                "id": "2540b5414f2d422291cea3162eb8e1e0",
                "file_extension": ".pdf",
                "updated_at": "2026-02-27T07:30:10.875503Z",
                "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
                "file_size": 889027,
                "file_metadata": {
                    "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS model service overview.pdf",
                    "file_name": "EAS model service overview.pdf",
                    "file_size": 889027,
                    "file_extension": ".pdf"
                },
                "message_id": "tmp-1772177410",
                "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
                "chunk_config": null,
                "file_content": "",
                "file_version": 1772177410
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 10
    }
}

ファイル詳細の取得

単一ファイルの詳細情報を返します。このエンドポイントを使用して、ファイル処理ステータスをポーリングします。

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}

リクエスト	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
ヘッダー
Authorization `string` (必須) 認証トークン。ご利用の `EAS_TOKEN` を使用します。
パスパラメーター
kb_id `string` (必須) ナレッジベース ID。
file_id `string` (必須) ファイル ID。

レスポンス例

{
    "code": 200,
    "message": "File query successful",
    "data": {
        "file_content_length": 0,
        "status": "succeeded",
        "file_source": null,
        "failed_reason": null,
        "file_name": "EASモデルサービスの概要.pdf",
        "active": true,
        "tenant_id": "__default_tenant_id__",
        "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EASモデルサービスの概要.pdf",
        "created_at": "2026-02-27T07:30:10.875488Z",
        "id": "2540b5414f2d422291cea3162eb8e1e0",
        "file_extension": ".pdf",
        "updated_at": "2026-02-27T07:30:10.875503Z",
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "file_size": 889027,
        "file_metadata": {
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EASモデルサービスの概要.pdf",
            "file_name": "EASモデルサービスの概要.pdf",
            "file_size": 889027,
            "file_extension": ".pdf",
            "file_url": "http://rag-test-****.oss-cn-hangzhou.aliyuncs.com/pairag_knowledgebases%2Fa4815ee728a64e9c83a3d891dbc1c956%2Fdocs%2FEAS%E6%A8%A1%E5%9E%8B%E6%9C%8D%E5%8A%A1%E6%A6%82%E8%BF%B0.pdf?OSSAccessKeyId=******&Expires=1772181413&Signature=IME****MxJ7Ys2%2BMwckrZsNfg%3D"
        },
        "message_id": "tmp-1772177410",
        "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
        "chunk_config": null,
        "file_content": "",
        "file_version": 1772177410
    }
}

ファイルの再処理

処理に失敗したファイルや更新されたファイルなどを再処理します。これは非同期操作で、新しい処理タスクを作成し、ファイルステータスを pending にリセットします。

PUT $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}

リクエスト	`curl -X PUT "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header 'Content-Type: application/json' \`
ヘッダー
Content-Type `string` (必須) リクエストのコンテンツタイプ。このパラメーターは `application/json` に設定する必要があります。
Authorization `string` (必須) リクエストの認証トークン。EAS_TOKEN を使用します。
パスパラメーター
kb_id `string` (必須) ナレッジベースの一意の識別子。
file_id `string` (必須) ファイルの一意の識別子。

レスポンス例

{
    "code": 200,
    "message": "Successfully added 1 files to the reprocessing queue.",
    "data": 1
}

ファイルの削除

ナレッジベースからファイルとその関連データチャンクおよびインデックスを削除します。

DELETE $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}

リクエスト	`curl -X DELETE "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
ヘッダー
Authorization `string` (必須) 認証トークン。ご利用の EAS_TOKEN を使用します。
パスパラメーター
kb_id `string` (必須) ナレッジベースの一意の識別子。
file_id `string` (必須) ファイルの一意の識別子。

レスポンス例

{
    "code": 200,
    "message": "Knowledge base file deleted successfully.",
    "data": null
}

データチャンク管理

ファイルチャンクのリスト表示

指定されたファイルからチャンクのページ分割されたリストを返します。

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks?page=1&size=10

リクエスト	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks?page=1&size=10" \ --header "Authorization: Bearer $EAS_TOKEN"`
リクエストヘッダー
Authorization `string` (必須) リクエストを認証するためのトークン。EAS_TOKEN を使用します。
パスパラメーター
kb_id `string` (必須) ナレッジベースの一意の識別子。
file_id `string` (必須) ファイルの一意の識別子。
クエリパラメーター
page `int` (任意) ページ番号。デフォルト値は 1 です。
size `int` (任意) ページあたりのチャンク数。デフォルト値は 10 です。

レスポンス例

{
    "code": 200,
    "message": "Chunk list retrieval successful",
    "data": {
        "items": [
            {
                "active": true,
                "text": "EAS model service overview******and other capabilities.\n\n",
                "chunk_metadata": {
                    "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
                    "file_name": "EAS_model_service_overview.pdf",
                    "file_size": 889027,
                    "file_extension": ".pdf",
                    "page_bbox": "[{\"page_idx\":1, \"bbox\":[77.600088, 73.57552407360004, 551.0441759999999, 239.87664000000007]}]",
                    "token_count": 196,
                    "doc_id": "2540b5414f2d422291cea3162eb8e1e0",
                    "images_info": []
                },
                "file_id": "2540b5414f2d422291cea3162eb8e1e0",
                "file_version": 0,
                "index": 0,
                "updated_at": "2026-02-27T07:42:00.167502Z",
                "status": "succeeded",
                "tenant_id": "__default_tenant_id__",
                "id": "e2b0d936158f4656a6cacb5ab639de6d",
                "file_part": 0,
                "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
                "created_at": "2026-02-27T07:42:00.167488Z"
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 10
    }
}

チャンクの更新

チャンクのコンテンツまたはステータスを更新します。たとえば、不適切に分割されたテキストを手動で修正したり、チャンクを無効にして取得から除外したりできます。

PUT $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks/{chunk_id}

リクエスト	`curl -X PUT "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/chunks/{chunk_id}" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "text": "The updated text content of the chunk...", "active": true }'`
リクエストヘッダー
Authorization `string` (必須) リクエストの認証トークン。EAS_TOKEN を使用します。
Content-Type `string` (必須) application/json
パスパラメーター
kb_id `string` (必須) ナレッジベースの一意の識別子。
file_id `string` (必須) ファイルの一意の識別子。
chunk_id `string` (必須) チャンクの一意の識別子。
リクエストボディ
text `string` (任意) チャンクの更新されたテキストコンテンツ。
active `bool` (任意) チャンクがアクティブかどうかを示します。false の場合、チャンクは取得から除外されます。

レスポンス例

{
    "code": 200,
    "message": "Chunk update successful",
    "data": {
        "active": true,
        "text": "Updated chunk text content...",
        "chunk_metadata": {
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
            "file_name": "EAS_model_service_overview.pdf",
            "file_size": 889027,
            "file_extension": ".pdf",
            "page_bbox": "[{\"page_idx\":1, \"bbox\":[77.600088, 73.57552407360004, 551.0441759999999, 239.87664000000007]}]",
            "token_count": 196,
            "doc_id": "2540b5414f2d422291cea3162eb8e1e0"
        },
        "file_id": "2540b5414f2d422291cea3162eb8e1e0",
        "file_version": 0,
        "index": 0,
        "updated_at": "2026-02-27T07:42:00.167502Z",
        "status": "succeeded",
        "tenant_id": "__default_tenant_id__",
        "id": "e2b0d936158f4656a6cacb5ab639de6d",
        "file_part": 0,
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "created_at": "2026-02-27T07:42:00.167488Z"
    }
}

チャンクの除外

更新操作を使用して、active フィールドを false に設定します。

メタデータ管理

メタデータはドキュメントに構造化された情報を追加し、取得時のより正確なフィルタリングを可能にします。たとえば、IT 部門が 2024 年以降に公開したドキュメントのみを取得できます。

メタデータフィールドの定義

ナレッジベースのメタデータフィールドのスキーマを定義します。これには、名前、値の型、説明が含まれます。

POST $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata

リクエスト	`curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "kb_id": "kb9594e2d2d2744bf1acd4227a9202b90b", "name": "expire_period", "value_type": "datetime", "description": "Product expiration date" }'`
ヘッダー
Authorization `string` (必須) リクエストの認証トークン。
Content-Type `string` (必須) application/json
パスパラメーター
kb_id `string` (必須) ナレッジベース ID。
リクエストボディ
kb_id `string` (必須) ナレッジベース ID。
name `string` (必須) メタデータフィールドの表示名。3〜50 文字である必要があります。
value_type `string` (必須) フィールドの値の型。string、number、または datetime である必要があります。
description `string` (任意) メタデータフィールドの説明。

レスポンス例

{
    "code": 200,
    "message": "Metadata created successfully.",
    "data": {
        "value_type": "datetime",
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "created_at": "2026-02-27T07:49:19.964621Z",
        "name": "expire_period",
        "id": "d2b5ef3cf07d459da7b91b83dbb0a533",
        "tenant_id": "__default_tenant_id__",
        "description": "Product expiration date",
        "updated_at": "2026-02-27T07:49:19.964632Z"
    }
}

メタデータのリスト表示

指定されたナレッジベースに定義されているすべてのメタデータフィールドをリスト表示します。

GET $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata

リクエスト	`curl -X GET "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata" \ --header "Authorization: Bearer $EAS_TOKEN"`
ヘッダー
Authorization `string` (必須) リクエストの認証トークン。
パスパラメーター
kb_id `string` (必須) ナレッジベース ID。

レスポンス例

{
    "code": 200,
    "message": "Metadata listed successfully.",
    "data": {
        "items": [
            {
                "value_type": "datetime",
                "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
                "created_at": "2026-02-27T07:49:19.964621Z",
                "name": "expire_period",
                "id": "d2b5ef3cf07d459da7b91b83dbb0a533",
                "tenant_id": "__default_tenant_id__",
                "description": "Product expiration date",
                "updated_at": "2026-02-27T07:49:19.964632Z",
                "count": 0
            }
        ],
        "total": 1,
        "pages": 1,
        "page": 1,
        "size": 20
    }
}

メタデータの削除

指定されたメタデータフィールドをナレッジベースから削除します。

DELETE $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata/{metadata_id}

リクエスト	`curl -X DELETE "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/metadata/{metadata_id}" \ --header "Authorization: Bearer $EAS_TOKEN"`
ヘッダー
Authorization `string` (必須) リクエストの認証トークン。
パスパラメーター
kb_id `string` (必須) ナレッジベース ID。
metadata_id `string` (必須) 削除するメタデータフィールドの ID。

レスポンス例

{
    "code": 200,
    "message": "Metadata deleted successfully.",
    "data": null
}

ファイルメタデータの設定

特定のファイルのメタデータを設定します。重要：この操作は、ファイルの既存のメタデータをすべて置き換えます。データ損失なしでメタデータを更新するには、まず GET リクエストで現在の値を取得し、それらを変更してから、このリクエストで完全な値のセットを送信します。

POST $EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/metadata

リクエスト	`curl -X POST "$EAS_SERVICE_URL/v1/config/knowledgebases/{kb_id}/files/{file_id}/metadata" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "entries": [ {"name": "expire_period", "value": 1764574102000}, {"name": "category", "value": "food"}, {"name": "price", "value": 12} ] }'`
ヘッダー
Authorization `string` (必須) リクエストの認証トークン。
Content-Type `string` (必須) application/json
パスパラメーター
kb_id `string` (必須) ナレッジベース ID。
file_id `string` (必須) ファイル ID。
リクエストボディ
entries `array` (必須) ファイルに設定するメタデータエントリの配列。プロパティ name `string` (必須) ナレッジベースにすでに定義されているメタデータフィールドの名前。 value `string/number` (必須) メタデータフィールドに割り当てる値。この値の型は、フィールドに定義された value_type と一致する必要があります。

レスポンス例

{
    "code": 200,
    "message": "File metadata set successfully.",
    "data": {
        "file_content_length": 0,
        "status": "succeeded",
        "file_source": null,
        "failed_reason": null,
        "file_name": "EAS_model_service_overview.pdf",
        "active": true,
        "tenant_id": "__default_tenant_id__",
        "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
        "created_at": "2026-02-27T07:30:10.875488Z",
        "id": "2540b5414f2d422291cea3162eb8e1e0",
        "file_extension": ".pdf",
        "updated_at": "2026-02-27T07:41:59.360291Z",
        "kb_id": "a4815ee728a64e9c83a3d891dbc1c956",
        "file_size": 889027,
        "file_metadata": {
            "file_path": "a4815ee728a64e9c83a3d891dbc1c956/docs/EAS_model_service_overview.pdf",
            "file_name": "EAS_model_service_overview.pdf",
            "file_size": 889027,
            "file_extension": ".pdf",
            "expire_period": 1764574102000,
            "category": "food"
        },
        "message_id": "tmp-1772177410",
        "file_md5": "f4b60d2b9fd9edec06649ce7b5d65cb0",
        "chunk_config": null,
        "file_content": "",
        "file_version": 1772178119
    }
}

Retrieval API

ハイブリッド取得 (テキスト + ベクトル + メタデータフィルタリング)

テキスト、ベクトル、メタデータフィルタリングを組み合わせて、指定されたナレッジベースでハイブリッド取得を実行します。

POST $EAS_SERVICE_URL/v1/retrieval

リクエスト	curl -X POST "$EAS_SERVICE_URL/v1/retrieval" \ --header "Authorization: Bearer $EAS_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "query": "recommendation system", "knowledge_id": "kbdeec6a87e7b342b6a0da7e67a171fbb4", "metadata_condition": { "conditions": [ {"name": "department", "value": "i", "comparison_operator": "start with"}, {"name": "age", "value": "23", "comparison_operator": "<"} ], "logical_operator": "and" }, "retrieval_setting": { "top_k": 2, "score_threshold": 0.4 } }'
ヘッダー
Authorization `string` (必須) リクエストの認証トークン。`EAS_TOKEN` を使用します。
Content-Type `string` (必須) application/json
リクエストボディ
query `string` (必須) クエリテキスト。
knowledge_id `string` (必須) ナレッジベースの ID。
user_id `string` (任意) パーソナライゼーションやロギングに使用されるユーザーの一意の識別子。
metadata_condition `object` (任意) メタデータフィルタリングの条件を指定します。これには、`logical_operator` と `conditions` 配列が含まれます。プロパティ logical_operator `string` (任意) 条件の論理演算子。デフォルトは `and` です。有効な値は `and` と `or` です。 conditions `array` (任意) 条件オブジェクトの配列。プロパティ name `string` (必須) メタデータフィールドの ID。 value `string/number` (必須) 比較値。 comparison_operator `string` (必須) 比較演算子。有効な値 `empty`：フィールドが null または空の文字列であるかを確認します。 `not empty`：フィールドに空でない値があるかを確認します。 `contains`：value パラメーターがフィールドの文字列値の部分文字列であるかを確認します。 `not contains`：value パラメーターがフィールドの文字列値の部分文字列でないことを確認します。 `start with`：フィールドの文字列値が value パラメーターで始まるかを確認します。 `end with`：フィールドの文字列値が value パラメーターで終わるかを確認します。 `=`：等しい。number 型と datetime 型に適用されます。 `≠`：等しくない。number 型と datetime 型に適用されます。 `≥`：以上。number 型と datetime 型に適用されます。 `≤`：以下。number 型と datetime 型に適用されます。 `>`：より大きい。number 型と datetime 型に適用されます。 `<`：より小さい。number 型と datetime 型に適用されます。
retrieval_setting `object` (任意) ナレッジベースのデフォルト設定を上書きするリクエストごとの設定。プロパティ top_k `int` (任意) 返す最も関連性の高いデータチャンクの数。 score_threshold `float` (任意) 類似度スコアのしきい値。このしきい値以上のスコアを持つデータチャンクのみが返されます。

レスポンス例

{
    "records": [
        {
            "content": "EasyRec is an easy-to-use recommendation framework...",
            "score": 0.5892808330916407,
            "title": "EasyRec.txt",
            "metadata": {
                "file_name": "EasyRec.txt",
                "department": "it"
            }
        }
    ]
}

コードサンドボックスの設定

サンドボックスの作成または更新

リクエスト	`curl -X POST "$EAS_SERVICE_URL/api/config/code_sandbox" \ -H "Authorization: Bearer $EAS_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "type": "aliyun-fc", "aliyun_id": "your-aliyun-id", "interpreter_id": "your-interpreter-id", "enabled": true }'`
リクエストヘッダー
Content-Type `string`(必須) リクエストのコンテンツタイプ。このパラメーターは `application/json` に設定する必要があります。
Authorization `string`(必須) リクエストの認証トークン。ご利用の EAS_TOKEN を使用します。
リクエストボディ
type `string`(必須) サンドボックスのタイプ。現在サポートされているのは Alibaba Cloud Function Compute (FC) サンドボックスのみであるため、これを `aliyun-fc` に設定します。
aliyun_id `string`(必須) ご利用の Alibaba Cloud アカウント ID。
interpreter_id `string`(必須) コードインタープリター ID。
enabled `bool`(必須) サンドボックスを有効にするには `true` に、無効にするには `false` に設定します。

サンドボックス設定の取得

curl -X GET "$EAS_SERVICE_URL/api/config/code_sandbox"

よくある質問 (FAQ) の設定

ベースパス：/v1/config/apps (アプリケーション設定)、/v1/faq-retrieval (FAQ 取得)

すべてのリクエストには権限付与が必要です (例：Authorization: Bearer YOUR_BEARER_TOKEN)。{EAS_SERVICE_URL} を実際のサービス URL に置き換えてください。

FAQ の有効化と設定

アプリケーション更新 API を使用して FAQ を有効にし、設定を適用します。

PUT {EAS_SERVICE_URL}/v1/config/apps/{id}

リクエスト	curl -X PUT "$EAS_SERVICE_URL/v1/config/apps/{id}" \ -H "Authorization: Bearer $EAS_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "app_id": "your_app_id", "description": "Application description", "model_id": "your_model_id", "kb_ids": [], "enable_faq": true, "faq_config": { "active": true, "similarity_threshold": 0.8, "embedding_model": "BAAI/bge-m3", "enable_question_in_retrieval": true, "enable_question_in_response": true, "enable_answer_in_retrieval": false, "enable_answer_in_response": true, "return_direct": false } }'
ヘッダー
Content-Type `string` (必須) リクエストのコンテンツタイプ。このパラメーターは `application/json` に設定する必要があります。
Authorization `string` (必須) リクエストの認証トークン。ご利用の `EAS_TOKEN` を使用します。
パスパラメーター
id `string` (必須) アプリケーションの一意の ID。アプリケーションのクエリ API を使用してこの ID を取得します。
リクエストボディ
app_id `string` (必須) アプリケーション ID。
description `string` (任意) アプリケーションの説明。
model_id `string` (必須) ベースモデルの ID。
kb_ids `array` (任意) アプリケーションに関連付けられたナレッジベース ID の配列。
enable_faq `bool` (任意) FAQ 機能を有効または無効にします。
faq_config `object` (任意) FAQ の設定。プロパティ active `bool` (任意) この FAQ 設定を有効または無効にします。 similarity_threshold `float` (任意) 類似度のしきい値。0.8 から 1.0 の間の値を推奨します。 embedding_model `string` (任意) 埋め込みモデル ID。 enable_question_in_retrieval `bool` (任意) 取得プロセスに質問を含めるかどうか。 enable_question_in_response `bool` (任意) 応答に質問を含めるかどうか。 enable_answer_in_retrieval `bool` (任意) 取得プロセスに回答を含めるかどうか。 enable_answer_in_response `bool` (任意) 応答に回答を含めるかどうか。 return_direct `bool` (任意) LLM 処理なしで、ツールの出力を直接返すかどうか。

アプリケーションのクエリ

curl -X GET "$EAS_SERVICE_URL/v1/config/apps?app_id=your_app_id" \
  -H "Authorization: Bearer $EAS_TOKEN"

app_id は次のように取得します。コンソールのアプリケーション設定ページで、[チャットアプリケーション] タブを選択し、必須の [App ID] フィールドでアプリケーション ID の値 (例：chatbot) を見つけ、それをリクエストの app_id パラメーターの値として使用します。

FAQ の作成

curl -X POST "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "How do I reset my password?",
    "answer": "On the sign-in page, click '\''Forgot Password'\'' and follow the prompts.",
    "active": true
  }'

FAQ のリスト表示

curl -X GET "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs?page=1&size=100" \
  -H "Authorization: Bearer $EAS_TOKEN"

FAQ の更新

curl -X PUT "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs/{faq_item_id}" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "How do I change my password?",
    "answer": "After signing in, go to Account Settings > Security to change your password.",
    "active": true
  }'

FAQ の削除

curl -X DELETE "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faqs/{faq_item_id}" \
  -H "Authorization: Bearer $EAS_TOKEN"

FAQ ファイルの一括アップロード

このリクエストは multipart/form-data を使用します。files フィールドを使用して 1 つ以上のファイルをアップロードします。オプションで table_config JSON 文字列を提供して、ヘッダーと列のインデックスをマッピングできます。サポートされているファイルタイプは .xlsx と .xls です。

curl -X POST "$EAS_SERVICE_URL/v1/config/apps/{app_id}/faq-files" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -F 'files=@/path/to/faq.xlsx' \
  -F 'table_config={"header_index_max":0,"question_column_index":0,"answer_column_index":1}'

table_config パラメーター：

header_index_max：最後のヘッダー行の 0 から始まるインデックス。単一のヘッダー行の場合、これを 0 に設定します。
question_column_index：質問列の 0 から始まるインデックス。
answer_column_index：回答列の 0 から始まるインデックス。

FAQ 取得 (スタンドアロン)

会話を開始せずに、クエリに対する FAQ の結果を直接取得します。

curl -X POST "$EAS_SERVICE_URL/v1/faq-retrieval" \
  -H "Authorization: Bearer $EAS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "chatapp_id": "your_app_id",
    "query": "User'\''s input query"
  }'

任意のリクエストフィールド：user_id と retrieval_setting (例：top_k、similarity_threshold)。retrieval_setting が省略された場合、アプリケーションのデフォルトの FAQ 設定が使用されます。

前提条件：エンドポイントとトークンの取得

Chat API

ナレッジベース管理

ナレッジベース

リクエスト

リクエストヘッダー

リクエストボディ

レスポンス例

ナレッジベースのリスト表示

リクエスト

リクエストヘッダー

クエリパラメーター

レスポンス例

ナレッジベースの取得

リクエスト

ヘッダー

パスパラメーター

レスポンス例

ナレッジベースの更新

リクエスト

リクエストヘッダー

パスパラメーター

リクエストボディ

レスポンス例

ナレッジベースの削除

リクエスト

リクエストヘッダー

パスパラメーター

レスポンス例

ファイル管理

ファイルのアップロード

リクエスト

リクエストヘッダー

パスパラメーター

リクエストボディ

レスポンス例

ファイルのリスト表示

リクエスト

リクエストヘッダー

パスパラメーター

クエリパラメーター

レスポンス例

ファイル詳細の取得

リクエスト

ヘッダー

パスパラメーター

レスポンス例

ファイルの再処理

リクエスト

ヘッダー

パスパラメーター

レスポンス例

ファイルの削除

リクエスト

ヘッダー

パスパラメーター

レスポンス例

データチャンク管理

ファイルチャンクのリスト表示

リクエスト

リクエストヘッダー

パスパラメーター

クエリパラメーター

レスポンス例

チャンクの更新

リクエスト

リクエストヘッダー

パスパラメーター

リクエストボディ

レスポンス例

チャンクの除外

メタデータ管理

メタデータフィールドの定義

リクエスト

ヘッダー

パスパラメーター

リクエストボディ

レスポンス例

メタデータのリスト表示

リクエスト