diff --git a/docs.json b/docs.json index d40ff22f..7f178c19 100644 --- a/docs.json +++ b/docs.json @@ -390,7 +390,7 @@ "en/development/models-integration/litellm", "en/development/models-integration/gpustack", "en/development/models-integration/aws-bedrock-deepseek", - "en/development/models-integration/truefoundry" + "en/development/models-integration/truefoundry", "en/development/models-integration/gpt-oss-local-deployment" ] }, @@ -1287,6 +1287,10 @@ { "group": "文本生成", "openapi": "zh-hans/openapi_completion.json" + }, + { + "group": "知识库 API", + "openapi": "zh-hans/openapi_knowledge.json" } ] }, @@ -1922,6 +1926,10 @@ { "group": "テキスト ジェネレーター", "openapi": "ja-jp/openapi_completion.json" + }, + { + "group": "ナレッジベース API", + "openapi": "ja-jp/openapi_knowledge.json" } ] }, diff --git a/en/openapi_knowledge.json b/en/openapi_knowledge.json index 6773045b..7b8a799a 100644 --- a/en/openapi_knowledge.json +++ b/en/openapi_knowledge.json @@ -1711,7 +1711,8 @@ "ApiKeyAuth": { "type": "http", "scheme": "bearer", - "description": "API Key authentication. Provide the key in the 'Authorization' header as 'Bearer {API_KEY}'." + "bearerFormat": "API_KEY", + "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with 'Bearer '. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" } }, "responses": { diff --git a/ja-jp/openapi_knowledge.json b/ja-jp/openapi_knowledge.json new file mode 100644 index 00000000..3428d6db --- /dev/null +++ b/ja-jp/openapi_knowledge.json @@ -0,0 +1,2983 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "ナレッジAPI", + "description": "ナレッジベース（データセット）、ドキュメント、セグメントの管理API。作成、取得、設定が可能です。", + "version": "1.0.0" + }, + "servers": [ + { + "url": "{apiBaseUrl}", + "description": "ナレッジAPIのベースURL。", + "variables": { + "apiBaseUrl": { + "default": "https://api.dify.ai/v1", + "description": "APIの実際のベースURL" + } + } + } + ], + "security": [ + { + "ApiKeyAuth": [] + } + ], + "tags": [ + { + "name": "データセット", + "description": "ナレッジベース（データセット）の管理に関連する操作。" + }, + { + "name": "ドキュメント", + "description": "データセット内のドキュメントの作成、更新、管理のための操作。" + }, + { + "name": "セグメント", + "description": "ドキュメントのチャンク（セグメント）の管理のための操作。" + }, + { + "name": "メタデータ・タグ", + "description": "データセットタグとメタデータの管理のための操作。" + }, + { + "name": "モデル", + "description": "利用可能なモデルの取得のための操作。" + } + ], + "paths": { + "/datasets": { + "post": { + "tags": [ + "データセット" + ], + "summary": "空のナレッジベースを作成", + "description": "指定された設定で新しい空のナレッジベース（データセット）を作成します。", + "operationId": "createDataset", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateDatasetRequest" + } + } + } + }, + "responses": { + "200": { + "description": "データセットの作成に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Dataset" + } + } + } + }, + "409": { + "$ref": "#/components/responses/DatasetNameDuplicate" + } + } + }, + "get": { + "tags": [ + "データセット" + ], + "summary": "ナレッジベースリストを取得", + "description": "ページネーションとフィルタリングのオプション付きでナレッジベースのリストを取得します。", + "operationId": "listDatasets", + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "名前でデータセットをフィルタするための検索キーワード。", + "schema": { + "type": "string" + } + }, + { + "name": "tag_ids", + "in": "query", + "description": "フィルタするタグIDのリスト。データセットは指定されたすべてのタグを持つ必要があります。", + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": false + }, + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1ページあたりに返すアイテム数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "include_all", + "in": "query", + "description": "すべてのデータセットを含めるかどうか。これはワークスペースオーナーにのみ有効です。", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "データセットのページネーションリスト。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DatasetListResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}": { + "get": { + "tags": [ + "データセット" + ], + "summary": "ナレッジベース詳細を取得", + "description": "IDで特定のナレッジベースの詳細情報を取得します。", + "operationId": "getDatasetDetail", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースの一意識別子。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "データセットに関する詳細情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DatasetDetail" + } + } + } + } + } + }, + "patch": { + "tags": [ + "データセット" + ], + "summary": "ナレッジベースを更新", + "description": "特定のナレッジベースの設定を更新します。", + "operationId": "updateDataset", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースの一意識別子。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateDatasetRequest" + } + } + } + }, + "responses": { + "200": { + "description": "データセット詳細の更新に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DatasetDetail" + } + } + } + }, + "409": { + "$ref": "#/components/responses/DatasetNameDuplicate" + } + } + }, + "delete": { + "tags": [ + "データセット" + ], + "summary": "ナレッジベースを削除", + "description": "ナレッジベースとそれに関連するすべてのドキュメントとデータを削除します。", + "operationId": "deleteDataset", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "削除するナレッジベースの一意識別子。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "データセットの削除に成功しました。" + } + } + } + }, + "/datasets/{dataset_id}/document/create-by-text": { + "post": { + "tags": [ + "ドキュメント" + ], + "summary": "テキストからドキュメントを作成", + "description": "テキストコンテンツから既存のナレッジベース内に新しいドキュメントを直接作成します。", + "operationId": "createDocumentFromText", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ドキュメントを追加するナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateDocumentByTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "ドキュメントが正常に作成され、インデックス化されています。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentCreationResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/document/create-by-file": { + "post": { + "tags": [ + "ドキュメント" + ], + "summary": "ファイルからドキュメントを作成", + "description": "ファイルをアップロードして既存のナレッジベース内に新しいドキュメントを作成します。", + "operationId": "createDocumentFromFile", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ドキュメントを追加するナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "string", + "description": "ドキュメントメタデータと処理ルールを含むJSON文字列。詳細は`CreateDocumentByFileRequestData`スキーマを参照してください。", + "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\":{\"separator\":\"###\", \"max_tokens\":500}}}}" + }, + "file": { + "type": "string", + "format": "binary", + "description": "アップロードするファイル。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "ドキュメントが正常に作成され、インデックス化されています。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentCreationResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/FileError" + }, + "413": { + "$ref": "#/components/responses/FileTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedFileType" + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { + "post": { + "tags": [ + "ドキュメント" + ], + "summary": "テキストでドキュメントを更新", + "description": "テキストを使用して既存のドキュメントのコンテンツまたは設定を更新します。", + "operationId": "updateDocumentByText", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ドキュメントを含むナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "更新するドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateDocumentByTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "ドキュメントが正常に更新されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentCreationResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { + "post": { + "tags": [ + "ドキュメント" + ], + "summary": "ファイルでドキュメントを更新", + "description": "新しいファイルをアップロードして既存のドキュメントを更新し、そのコンテンツを置き換えます。", + "operationId": "updateDocumentByFile", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ドキュメントを含むナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "更新するドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "string", + "description": "オプションのドキュメント名と処理ルールを含むJSON文字列。`UpdateDocumentByFileRequestData`スキーマを参照してください。", + "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}" + }, + "file": { + "type": "string", + "format": "binary", + "description": "アップロードする新しいファイル。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "ドキュメントが正常に更新されました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentCreationResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "get": { + "tags": [ + "ドキュメント" + ], + "summary": "ドキュメント埋め込みステータス（進捗）を取得", + "description": "ドキュメントのバッチのインデックス化ステータスを取得し、埋め込みと処理の進捗を表示します。", + "operationId": "getDocumentIndexingStatus", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "batch", + "in": "path", + "required": true, + "description": "ドキュメント作成エンドポイントから返されるバッチ番号。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "バッチ内のドキュメントのインデックス化ステータス。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IndexingStatus" + } + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}": { + "get": { + "tags": [ + "ドキュメント" + ], + "summary": "ドキュメント詳細を取得", + "description": "処理ルールとステータスを含む単一ドキュメントの詳細情報を取得します。", + "operationId": "getDocumentDetail", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "metadata", + "in": "query", + "description": "メタデータフィルタ：`all`はすべてのメタデータを返し、`only`はカスタムメタデータのみを返し、`without`はメタデータを返しません。", + "schema": { + "type": "string", + "enum": [ + "all", + "only", + "without" + ], + "default": "all" + } + } + ], + "responses": { + "200": { + "description": "ドキュメントに関する詳細情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentDetail" + } + } + } + } + } + }, + "delete": { + "tags": [ + "ドキュメント" + ], + "summary": "ドキュメントを削除", + "description": "ナレッジベースから特定のドキュメントを削除します。", + "operationId": "deleteDocument", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "削除するドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "ドキュメントの削除に成功しました。" + } + } + } + }, + "/datasets/{dataset_id}/documents": { + "get": { + "tags": [ + "ドキュメント" + ], + "summary": "ナレッジベースのドキュメントリストを取得", + "description": "指定されたナレッジベース内のすべてのドキュメントのページネーションリストを取得します。", + "operationId": "listDocuments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "keyword", + "in": "query", + "description": "ドキュメント名で検索するキーワード。", + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1ページあたりに返すアイテム数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "ドキュメントのページネーションリスト。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentListResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/status/{action}": { + "patch": { + "tags": [ + "ドキュメント" + ], + "summary": "ドキュメントステータスを更新", + "description": "1つまたは複数のドキュメントのステータスを更新するバッチアクションを実行します（例：有効化、無効化、アーカイブ）。", + "operationId": "batchUpdateDocumentStatus", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "action", + "in": "path", + "required": true, + "description": "ドキュメントに対して実行するアクション。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable", + "archive", + "un_archive" + ] + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "description": "アクションを実行するドキュメントIDのリスト。", + "items": { + "type": "string", + "format": "uuid" + } + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/Success" + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments": { + "post": { + "tags": [ + "セグメント" + ], + "summary": "ドキュメントにチャンクを追加", + "description": "特定のドキュメントに1つまたは複数の新しいチャンク（セグメント）を追加します。手動でキュレートされたコンテンツを追加するのに便利です。", + "operationId": "createSegments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSegmentsRequest" + } + } + } + }, + "responses": { + "200": { + "description": "新しく作成されたセグメントのリスト。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SegmentListResponse" + } + } + } + } + } + }, + "get": { + "tags": [ + "セグメント" + ], + "summary": "ドキュメントからチャンクを取得", + "description": "特定のドキュメントからチャンク（セグメント）のページネーションリストを取得します。", + "operationId": "listSegments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "keyword", + "in": "query", + "description": "コンテンツでセグメントをフィルタするキーワード。", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "インデックス化ステータスでセグメントをフィルタ。", + "schema": { + "type": "string", + "example": "completed" + } + }, + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1ページあたりに返すアイテム数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "セグメントのページネーションリスト。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SegmentPaginatedResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { + "get": { + "tags": [ + "セグメント" + ], + "summary": "ドキュメント内のチャンク詳細を取得", + "description": "ドキュメント内の特定のチャンク（セグメント）の詳細を取得します。", + "operationId": "getSegmentDetail", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "セグメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "セグメントに関する詳細情報。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SegmentDetailResponse" + } + } + } + } + } + }, + "post": { + "tags": [ + "セグメント" + ], + "summary": "ドキュメント内のチャンクを更新", + "description": "特定のチャンク（セグメント）のコンテンツ、キーワード、またはステータスを更新します。", + "operationId": "updateSegment", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "更新するセグメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateSegmentRequest" + } + } + } + }, + "responses": { + "200": { + "description": "更新されたセグメント詳細。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SegmentDetailResponse" + } + } + } + } + } + }, + "delete": { + "tags": [ + "セグメント" + ], + "summary": "ドキュメント内のチャンクを削除", + "description": "ドキュメントから特定のチャンク（セグメント）を削除します。", + "operationId": "deleteSegment", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "削除するセグメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "セグメントの削除に成功しました。" + } + } + } + }, + "/datasets/{dataset_id}/retrieve": { + "post": { + "tags": [ + "データセット" + ], + "summary": "ナレッジベースからチャンクを取得", + "description": "ナレッジベースに対して検索クエリを実行し、最も関連性の高いチャンク（セグメント）を取得します。", + "operationId": "retrieveSegments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "取得元のナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetrieveRequest" + } + } + } + }, + "responses": { + "200": { + "description": "クエリにマッチする取得されたセグメントのリスト。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetrieveResponse" + } + } + } + } + } + } + }, + "/workspaces/current/models/model-types/text-embedding": { + "get": { + "tags": [ + "モデル" + ], + "summary": "利用可能な埋め込みモデルを取得", + "description": "ナレッジベースの作成とクエリに使用できるすべての利用可能なテキスト埋め込みモデルのリストを取得します。", + "operationId": "getAvailableEmbeddingModels", + "responses": { + "200": { + "description": "プロバイダー別にグループ化された利用可能な埋め込みモデルのリスト。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ModelProvider" + } + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { + "post": { + "tags": [ + "セグメント" + ], + "summary": "子チャンクを作成", + "description": "階層モードを使用してドキュメント内の親セグメントの下に新しい子チャンクを作成します。", + "operationId": "createChildChunk", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "親セグメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateChildChunkRequest" + } + } + } + }, + "responses": { + "200": { + "description": "子チャンクの作成に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChildChunkResponse" + } + } + } + } + } + }, + "get": { + "tags": [ + "セグメント" + ], + "summary": "子チャンクを取得", + "description": "特定の親セグメントの子チャンクのリストを取得します。", + "operationId": "getChildChunks", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "親セグメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "keyword", + "in": "query", + "description": "子チャンクをフィルタする検索キーワード。", + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "ページネーションのページ番号。", + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "1ページあたりに返すアイテム数。", + "schema": { + "type": "integer", + "default": 20, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "子チャンクのページネーションリスト。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChildChunkListResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { + "patch": { + "tags": [ + "セグメント" + ], + "summary": "子チャンクを更新", + "description": "特定の子チャンクのコンテンツを更新します。", + "operationId": "updateChildChunk", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "親セグメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "child_chunk_id", + "in": "path", + "required": true, + "description": "更新する子チャンクのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateChildChunkRequest" + } + } + } + }, + "responses": { + "200": { + "description": "子チャンクの更新に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChildChunkResponse" + } + } + } + } + } + }, + "delete": { + "tags": [ + "セグメント" + ], + "summary": "子チャンクを削除", + "description": "特定の子チャンクを削除します。", + "operationId": "deleteChildChunk", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "親セグメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "child_chunk_id", + "in": "path", + "required": true, + "description": "削除する子チャンクのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "子チャンクの削除に成功しました。" + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/upload-file": { + "get": { + "tags": [ + "ドキュメント" + ], + "summary": "アップロードファイルを取得", + "description": "ダウンロードURLを含む、ドキュメント用にアップロードされた元のファイルの情報を取得します。", + "operationId": "getUploadFile", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "ナレッジベースのID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "ドキュメントのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "アップロードされたファイルの詳細。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UploadFileResponse" + } + } + } + } + } + } + }, + "/datasets/tags": { + "post": { + "tags": [ + "メタデータ・タグ" + ], + "summary": "新しいナレッジベースタイプタグを作成", + "description": "ナレッジベースを分類するために使用できる新しいタグを作成します。", + "operationId": "createKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["name"], + "properties": { + "name": { + "type": "string", + "description": "新しいタグの名前。", + "maxLength": 50 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "タグの作成に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + } + } + } + } + } + }, + "get": { + "tags": [ + "メタデータ・タグ" + ], + "summary": "ナレッジベースタイプタグを取得", + "description": "利用可能なすべてのナレッジベースタグのリストを取得します。", + "operationId": "getKnowledgeTags", + "responses": { + "200": { + "description": "タグのリスト。", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Tag" + } + } + } + } + } + } + }, + "patch": { + "tags": [ + "メタデータ・タグ" + ], + "summary": "ナレッジベースタイプタグ名を変更", + "description": "既存のタグの名前を更新します。", + "operationId": "updateKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["tag_id", "name"], + "properties": { + "tag_id": { + "type": "string", + "description": "変更するタグのID。", + "format": "uuid" + }, + "name": { + "type": "string", + "description": "タグの新しい名前。", + "maxLength": 50 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "タグの更新に成功しました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + } + } + } + } + } + }, + "delete": { + "tags": [ + "メタデータ・タグ" + ], + "summary": "ナレッジベースタイプタグを削除", + "description": "タグを削除します。タグはどのナレッジベースにもバインドされていない必要があります。", + "operationId": "deleteKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["tag_id"], + "properties": { + "tag_id": { + "type": "string", + "description": "削除するタグのID。", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/Success" + } + } + } + }, + "/datasets/tags/binding": { + "post": { + "tags": [ + "メタデータ・タグ" + ], + "summary": "データセットをナレッジベースタイプタグにバインド", + "description": "1つまたは複数のタグを特定のナレッジベースにバインドします。", + "operationId": "bindTagsToDataset", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["target_id", "tag_ids"], + "properties": { + "target_id": { + "type": "string", + "description": "タグをバインドするデータセットのID。", + "format": "uuid" + }, + "tag_ids": { + "type": "array", + "description": "バインドするタグIDのリスト。", + "items": { + "type": "string", + "format": "uuid" + } + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/Success" + } + } + } + }, + "/datasets/tags/unbinding": { + "post": { + "tags": [ + "メタデータ・タグ" + ], + "summary": "データセットとナレッジベースタイプタグのバインドを解除", + "description": "ナレッジベースから特定のタグのバインドを解除します。", + "operationId": "unbindTagFromDataset", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["target_id", "tag_id"], + "properties": { + "target_id": { + "type": "string", + "description": "データセットのID。", + "format": "uuid" + }, + "tag_id": { + "type": "string", + "description": "バインドを解除するタグのID。", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/Success" + } + } + } + }, + "/datasets/{dataset_id}/tags": { + "post": { + "tags": [ + "メタデータ・タグ" + ], + "summary": "データセットにバインドされたタグをクエリ", + "description": "特定のデータセットに現在バインドされているすべてのタグを取得します。", + "operationId": "queryDatasetTags", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "データセットのID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "データセットにバインドされたタグのリスト。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" } + } + } + }, + "total": { + "type": "integer" + } + } + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "APIキー認証。すべてのAPIリクエストにおいて、Authorization HTTPヘッダーにAPIキーを含めてください。形式：Bearer {API_KEY}。**APIキーの漏洩を防ぐため、APIキーはクライアント側で共有または保存せず、サーバー側で保存することを強くお勧めします。**" + } + }, + "responses": { + "Success": { + "description": "操作に成功しました。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "example": "success" + } + } + } + } + } + }, + "FileError": { + "description": "ファイルアップロードに関連する不正なリクエスト。`no_file_uploaded` または `too_many_files` の可能性があります。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "FileTooLarge": { + "description": "ファイルサイズが上限を超えました。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "UnsupportedFileType": { + "description": "ファイルタイプが許可されていません。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "DatasetNameDuplicate": { + "description": "データセット名が既に存在します。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "schemas": { + "ErrorResponse": { + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "機械読み取り可能なエラーコード。" + }, + "message": { + "type": "string", + "description": "人間が読めるエラーメッセージ。" + }, + "status": { + "type": "integer", + "description": "HTTPステータスコード。" + } + }, + "example": { + "code": "no_file_uploaded", + "message": "ファイルをアップロードしてください。", + "status": 400 + } + }, + "RetrievalModel": { + "type": "object", + "properties": { + "search_method": { + "type": "string", + "description": "取得に使用する検索方法。", + "enum": [ + "hybrid_search", + "semantic_search", + "full_text_search", + "keyword_search" + ] + }, + "reranking_enable": { + "type": "boolean", + "description": "検索結果を改善するためのリランキングモデルを有効にするかどうか。" + }, + "reranking_mode": { + "type": "object", + "description": "リランキングモデルの設定。", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "リランクモデルのプロバイダー。" + }, + "reranking_model_name": { + "type": "string", + "description": "リランクモデルの名前。" + } + }, + "nullable": true + }, + "top_k": { + "type": "integer", + "description": "返すトップマッチング結果の数。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "結果をフィルタするためのスコア閾値を適用するかどうか。" + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "結果に含まれる最小スコア。", + "nullable": true + }, + "weights": { + "type": "number", + "format": "float", + "description": "ハイブリッド検索モードでのセマンティック検索の重み。", + "nullable": true + } + } + }, + "PreprocessingRule": { + "type": "object", + "description": "ドキュメントコンテンツの前処理ルール。", + "properties": { + "id": { + "type": "string", + "description": "前処理ルールの一意識別子。", + "enum": [ + "remove_extra_spaces", + "remove_urls_emails" + ] + }, + "enabled": { + "type": "boolean", + "description": "このルールが有効かどうか。" + } + } + }, + "SegmentationRule": { + "type": "object", + "description": "ドキュメントコンテンツをチャンクにセグメント化するためのルール。", + "properties": { + "separator": { + "type": "string", + "description": "セグメントを分離するために使用するカスタム区切り文字。" + }, + "max_tokens": { + "type": "integer", + "description": "単一セグメントで許可される最大トークン数。" + } + } + }, + "SubChunkSegmentationRule": { + "type": "object", + "description": "親チャンクを小さな子チャンクにセグメント化するためのルール（階層モード用）。", + "properties": { + "separator": { + "type": "string", + "description": "サブチャンク化の区切り文字。" + }, + "max_tokens": { + "type": "integer", + "description": "サブチャンクの最大トークン長。" + }, + "chunk_overlap": { + "type": "integer", + "description": "隣接するサブチャンク間の重複トークン数。" + } + } + }, + "ProcessRule": { + "type": "object", + "description": "クリーニングとセグメント化を含む、ドキュメントを処理するためのルールセット。", + "properties": { + "mode": { + "type": "string", + "description": "処理モード：automatic、custom、またはhierarchical。", + "enum": [ + "automatic", + "custom", + "hierarchical" + ] + }, + "rules": { + "type": "object", + "description": "適用する特定のルール、モードが'custom'または'hierarchical'の場合に使用。", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PreprocessingRule" + } + }, + "segmentation": { + "$ref": "#/components/schemas/SegmentationRule" + }, + "parent_mode": { + "type": "string", + "description": "階層モードでの親チャンクの取得モード。", + "enum": [ + "full-doc", + "paragraph" + ] + }, + "subchunk_segmentation": { + "$ref": "#/components/schemas/SubChunkSegmentationRule" + } + }, + "nullable": true + } + } + }, + "CreateDocumentByTextRequest": { + "type": "object", + "required": [ + "name", + "text" + ], + "properties": { + "name": { + "type": "string", + "description": "ドキュメントの名前。" + }, + "text": { + "type": "string", + "description": "ドキュメントの完全なテキストコンテンツ。" + }, + "indexing_technique": { + "type": "string", + "description": "ドキュメントのインデックス化技術。", + "enum": [ + "high_quality", + "economy" + ] + }, + "doc_form": { + "type": "string", + "description": "インデックス化されたコンテンツの形式。", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ] + }, + "doc_language": { + "type": "string", + "description": "ドキュメントの言語、Q&Aモードで重要。", + "example": "Japanese" + }, + "process_rule": { + "$ref": "#/components/schemas/ProcessRule" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel" + }, + "embedding_model": { + "type": "string", + "description": "使用する埋め込みモデルの名前。" + }, + "embedding_model_provider": { + "type": "string", + "description": "埋め込みモデルのプロバイダー。" + } + } + }, + "CreateDocumentByFileRequestData": { + "type": "object", + "description": "ファイルからドキュメントを作成するためのメタデータとルール。", + "properties": { + "original_document_id": { + "type": "string", + "description": "再アップロードまたは修正する既存のドキュメントのID。", + "format": "uuid" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ] + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ] + }, + "doc_language": { + "type": "string", + "example": "Japanese" + }, + "process_rule": { + "$ref": "#/components/schemas/ProcessRule" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel" + }, + "embedding_model": { + "type": "string" + }, + "embedding_model_provider": { + "type": "string" + } + } + }, + "UpdateDocumentByTextRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "ドキュメントの新しい名前（オプション）。" + }, + "text": { + "type": "string", + "description": "ドキュメントの新しいテキストコンテンツ（オプション）。" + }, + "process_rule": { + "$ref": "#/components/schemas/ProcessRule" + } + } + }, + "UpdateDocumentByFileRequestData": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "ドキュメントの新しい名前（オプション）。" + }, + "process_rule": { + "$ref": "#/components/schemas/ProcessRule" + } + } + }, + "Document": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "position": { + "type": "integer" + }, + "data_source_type": { + "type": "string" + }, + "data_source_info": { + "type": "object", + "nullable": true + }, + "dataset_process_rule_id": { + "type": "string", + "format": "uuid", + "nullable": true + }, + "name": { + "type": "string" + }, + "created_from": { + "type": "string" + }, + "created_by": { + "type": "string", + "format": "uuid" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "tokens": { + "type": "integer" + }, + "indexing_status": { + "type": "string" + }, + "error": { + "type": "string", + "nullable": true + }, + "enabled": { + "type": "boolean" + }, + "disabled_at": { + "type": "integer", + "format": "int64", + "nullable": true + }, + "disabled_by": { + "type": "string", + "format": "uuid", + "nullable": true + }, + "archived": { + "type": "boolean" + }, + "display_status": { + "type": "string" + }, + "word_count": { + "type": "integer" + }, + "hit_count": { + "type": "integer" + }, + "doc_form": { + "type": "string" + } + } + }, + "DocumentCreationResponse": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "インデックス化の進捗を追跡するためのバッチ識別子。" + } + } + }, + "CreateDatasetRequest": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "ナレッジベースの名前。" + }, + "description": { + "type": "string", + "description": "ナレッジベースの説明（オプション）。" + }, + "indexing_technique": { + "type": "string", + "description": "使用するインデックス化技術。", + "enum": [ + "high_quality", + "economy" + ] + }, + "permission": { + "type": "string", + "description": "ナレッジベースのアクセス権限。", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ] + }, + "provider": { + "type": "string", + "description": "ナレッジベースのプロバイダー。", + "enum": [ + "vendor", + "external" + ] + }, + "external_knowledge_api_id": { + "type": "string", + "description": "外部ナレッジAPIのID（プロバイダーが'external'の場合）。" + }, + "external_knowledge_id": { + "type": "string", + "description": "外部ナレッジのID（プロバイダーが'external'の場合）。" + }, + "embedding_model": { + "type": "string", + "description": "埋め込みモデルの名前。" + }, + "embedding_model_provider": { + "type": "string", + "description": "埋め込みモデルのプロバイダー。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel" + } + } + }, + "Dataset": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string", + "nullable": true + }, + "provider": { + "type": "string" + }, + "permission": { + "type": "string" + }, + "data_source_type": { + "type": "string", + "nullable": true + }, + "indexing_technique": { + "type": "string", + "nullable": true + }, + "app_count": { + "type": "integer" + }, + "document_count": { + "type": "integer" + }, + "word_count": { + "type": "integer" + }, + "created_by": { + "type": "string", + "format": "uuid" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "updated_by": { + "type": "string", + "format": "uuid" + }, + "updated_at": { + "type": "integer", + "format": "int64" + }, + "embedding_model": { + "type": "string", + "nullable": true + }, + "embedding_model_provider": { + "type": "string", + "nullable": true + }, + "embedding_available": { + "type": "boolean", + "nullable": true + } + } + }, + "DatasetListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Dataset" + } + }, + "has_more": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "page": { + "type": "integer" + } + } + }, + "DatasetDetail": { + "allOf": [ + { + "$ref": "#/components/schemas/Dataset" + }, + { + "type": "object", + "properties": { + "retrieval_model_dict": { + "$ref": "#/components/schemas/RetrievalModel" + }, + "tags": { + "type": "array", + "items": { + "type": "object" + } + }, + "doc_form": { + "type": "string", + "nullable": true + } + } + } + ] + }, + "UpdateDatasetRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "ナレッジベースの新しい名前。" + }, + "description": { + "type": "string", + "description": "ナレッジベースの新しい説明。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ] + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ] + }, + "embedding_model_provider": { + "type": "string" + }, + "embedding_model": { + "type": "string" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel" + }, + "partial_member_list": { + "type": "array", + "description": "'partial_members'権限のメンバーIDリスト。", + "items": { + "type": "string" + } + } + } + }, + "IndexingStatus": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "indexing_status": { + "type": "string" + }, + "processing_started_at": { + "type": "number", + "format": "float" + }, + "parsing_completed_at": { + "type": "number", + "format": "float" + }, + "cleaning_completed_at": { + "type": "number", + "format": "float" + }, + "splitting_completed_at": { + "type": "number", + "format": "float" + }, + "completed_at": { + "type": "number", + "format": "float", + "nullable": true + }, + "paused_at": { + "type": "number", + "format": "float", + "nullable": true + }, + "error": { + "type": "string", + "nullable": true + }, + "stopped_at": { + "type": "number", + "format": "float", + "nullable": true + }, + "completed_segments": { + "type": "integer" + }, + "total_segments": { + "type": "integer" + } + } + }, + "DocumentListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Document" + } + }, + "has_more": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "page": { + "type": "integer" + } + } + }, + "DocumentDetail": { + "allOf": [ + { + "$ref": "#/components/schemas/Document" + }, + { + "type": "object", + "properties": { + "dataset_process_rule": { + "$ref": "#/components/schemas/ProcessRule" + }, + "document_process_rule": { + "allOf": [ + { + "$ref": "#/components/schemas/ProcessRule" + }, + { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "dataset_id": { + "type": "string" + } + } + } + ] + }, + "indexing_latency": { + "type": "number", + "format": "float", + "nullable": true + }, + "segment_count": { + "type": "integer" + }, + "average_segment_length": { + "type": "integer" + }, + "doc_language": { + "type": "string", + "nullable": true + } + } + } + ] + }, + "Segment": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "position": { + "type": "integer" + }, + "document_id": { + "type": "string", + "format": "uuid" + }, + "content": { + "type": "string" + }, + "answer": { + "type": "string", + "nullable": true + }, + "word_count": { + "type": "integer" + }, + "tokens": { + "type": "integer" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + } + }, + "index_node_id": { + "type": "string" + }, + "index_node_hash": { + "type": "string" + }, + "hit_count": { + "type": "integer" + }, + "enabled": { + "type": "boolean" + }, + "disabled_at": { + "type": "integer", + "format": "int64", + "nullable": true + }, + "disabled_by": { + "type": "string", + "format": "uuid", + "nullable": true + }, + "status": { + "type": "string" + }, + "created_by": { + "type": "string", + "format": "uuid" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "indexing_at": { + "type": "integer", + "format": "int64" + }, + "completed_at": { + "type": "integer", + "format": "int64" + }, + "error": { + "type": "string", + "nullable": true + }, + "stopped_at": { + "type": "integer", + "format": "int64", + "nullable": true + } + } + }, + "CreateSegmentsRequest": { + "type": "object", + "properties": { + "segments": { + "type": "array", + "items": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "description": "チャンクのテキストコンテンツ（Q&Aモードでは質問）。" + }, + "answer": { + "type": "string", + "description": "回答コンテンツ、ドキュメントがQ&Aモードの場合は必須。" + }, + "keywords": { + "type": "array", + "description": "チャンクに関連付けられたキーワード。", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "SegmentListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + } + }, + "doc_form": { + "type": "string" + } + } + }, + "SegmentPaginatedResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/SegmentListResponse" + }, + { + "type": "object", + "properties": { + "has_more": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "page": { + "type": "integer" + } + } + } + ] + }, + "SegmentDetailResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string" + } + } + }, + "UpdateSegmentRequest": { + "type": "object", + "properties": { + "segment": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string" + }, + "answer": { + "type": "string" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + } + }, + "enabled": { + "type": "boolean" + }, + "regenerate_child_chunks": { + "type": "boolean", + "description": "子チャンクを再生成するかどうか（階層モード）。" + } + } + } + } + }, + "RetrieveRequest": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "description": "検索クエリ文字列。" + }, + "retrieval_model": { + "allOf": [ + { + "$ref": "#/components/schemas/RetrievalModel" + }, + { + "type": "object", + "properties": { + "metadata_filtering_conditions": { + "type": "object", + "description": "メタデータに基づいて結果をフィルタする条件。", + "properties": { + "logical_operator": { + "type": "string", + "enum": [ + "and", + "or" + ] + }, + "conditions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "メタデータフィールドの名前。" + }, + "comparison_operator": { + "type": "string", + "description": "比較の演算子。" + }, + "value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + } + ], + "nullable": true, + "description": "比較する値。" + } + } + } + } + } + } + } + } + ] + } + } + }, + "RetrievedSegment": { + "type": "object", + "properties": { + "segment": { + "allOf": [ + { + "$ref": "#/components/schemas/Segment" + }, + { + "type": "object", + "properties": { + "document": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "data_source_type": { + "type": "string" + }, + "name": { + "type": "string" + } + } + } + } + } + ] + }, + "score": { + "type": "number", + "format": "float" + } + } + }, + "RetrieveResponse": { + "type": "object", + "properties": { + "query": { + "type": "object", + "properties": { + "content": { + "type": "string" + } + } + }, + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RetrievedSegment" + } + } + } + }, + "Model": { + "type": "object", + "properties": { + "model": { + "type": "string" + }, + "label": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "model_type": { + "type": "string" + }, + "features": { + "type": "array", + "items": {}, + "nullable": true + }, + "fetch_from": { + "type": "string" + }, + "model_properties": { + "type": "object", + "properties": { + "context_size": { + "type": "integer" + } + } + }, + "deprecated": { + "type": "boolean" + }, + "status": { + "type": "string" + }, + "load_balancing_enabled": { + "type": "boolean" + } + } + }, + "ModelProvider": { + "type": "object", + "properties": { + "provider": { + "type": "string" + }, + "label": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "icon_small": { + "type": "object", + "additionalProperties": { + "type": "string", + "format": "uri" + } + }, + "icon_large": { + "type": "object", + "additionalProperties": { + "type": "string", + "format": "uri" + } + }, + "status": { + "type": "string" + }, + "models": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Model" + } + } + } + }, + "ChildChunk": { + "type": "object", + "description": "階層セグメント化における子チャンクを表します。", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "segment_id": { "type": "string", "format": "uuid" }, + "content": { "type": "string" }, + "word_count": { "type": "integer" }, + "tokens": { "type": "integer" }, + "index_node_id": { "type": "string" }, + "index_node_hash": { "type": "string" }, + "status": { "type": "string" }, + "created_by": { "type": "string", "format": "uuid" }, + "created_at": { "type": "integer", "format": "int64" }, + "indexing_at": { "type": "integer", "format": "int64" }, + "completed_at": { "type": "integer", "format": "int64" }, + "error": { "type": "string", "nullable": true }, + "stopped_at": { "type": "integer", "format": "int64", "nullable": true } + } + }, + "CreateChildChunkRequest": { + "type": "object", + "required": ["content"], + "properties": { + "content": { + "type": "string", + "description": "子チャンクのコンテンツ。" + } + } + }, + "UpdateChildChunkRequest": { + "type": "object", + "required": ["content"], + "properties": { + "content": { + "type": "string", + "description": "子チャンクの更新されたコンテンツ。" + } + } + }, + "ChildChunkResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "ChildChunkListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChildChunk" + } + }, + "total": { "type": "integer" }, + "total_pages": { "type": "integer" }, + "page": { "type": "integer" }, + "limit": { "type": "integer" } + } + }, + "UploadFileResponse": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" }, + "size": { "type": "integer" }, + "extension": { "type": "string" }, + "url": { "type": "string", "format": "uri", "description": "ファイルのプレビューURL。" }, + "download_url": { "type": "string", "format": "uri", "description": "ファイルのダウンロードURL。" }, + "mime_type": { "type": "string" }, + "created_by": { "type": "string", "format": "uuid" }, + "created_at": { "type": "integer", "format": "int64" } + } + }, + "Tag": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" }, + "type": { "type": "string", "example": "knowledge" }, + "binding_count": { "type": "integer" } + } + } + } + } +} \ No newline at end of file diff --git a/zh-hans/openapi_knowledge.json b/zh-hans/openapi_knowledge.json new file mode 100644 index 00000000..114d3cac --- /dev/null +++ b/zh-hans/openapi_knowledge.json @@ -0,0 +1,2983 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "知识库 API", + "description": "用于管理知识库（数据集）、文档和段落的 API，包括创建、检索和配置功能。", + "version": "1.0.0" + }, + "servers": [ + { + "url": "{apiBaseUrl}", + "description": "知识库 API 的基础 URL。", + "variables": { + "apiBaseUrl": { + "default": "https://api.dify.ai/v1", + "description": "API 的实际基础 URL" + } + } + } + ], + "security": [ + { + "ApiKeyAuth": [] + } + ], + "tags": [ + { + "name": "数据集", + "description": "与管理知识库（数据集）相关的操作。" + }, + { + "name": "文档", + "description": "用于在数据集中创建、更新和管理文档的操作。" + }, + { + "name": "段落", + "description": "用于管理文档块（段落）的操作。" + }, + { + "name": "元数据和标签", + "description": "用于管理数据集标签和元数据的操作。" + }, + { + "name": "模型", + "description": "用于检索可用模型的操作。" + } + ], + "paths": { + "/datasets": { + "post": { + "tags": [ + "数据集" + ], + "summary": "创建空知识库", + "description": "使用指定配置创建一个新的空知识库（数据集）。", + "operationId": "createDataset", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateDatasetRequest" + } + } + } + }, + "responses": { + "200": { + "description": "成功创建数据集。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Dataset" + } + } + } + }, + "409": { + "$ref": "#/components/responses/DatasetNameDuplicate" + } + } + }, + "get": { + "tags": [ + "数据集" + ], + "summary": "获取知识库列表", + "description": "检索知识库列表，支持分页和过滤选项。", + "operationId": "listDatasets", + "parameters": [ + { + "name": "keyword", + "in": "query", + "description": "按名称过滤数据集的搜索关键词。", + "schema": { + "type": "string" + } + }, + { + "name": "tag_ids", + "in": "query", + "description": "要过滤的标签 ID 列表。数据集必须具有所有指定的标签。", + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "style": "form", + "explode": false + }, + { + "name": "page", + "in": "query", + "description": "分页的页码。", + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页返回的项目数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "include_all", + "in": "query", + "description": "是否包含所有数据集。这仅对工作区所有者有效。", + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "200": { + "description": "数据集的分页列表。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DatasetListResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}": { + "get": { + "tags": [ + "数据集" + ], + "summary": "获取知识库详情", + "description": "通过 ID 获取特定知识库的详细信息。", + "operationId": "getDatasetDetail", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的唯一标识符。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "关于数据集的详细信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DatasetDetail" + } + } + } + } + } + }, + "patch": { + "tags": [ + "数据集" + ], + "summary": "更新知识库", + "description": "更新特定知识库的设置。", + "operationId": "updateDataset", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的唯一标识符。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateDatasetRequest" + } + } + } + }, + "responses": { + "200": { + "description": "成功更新数据集详情。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DatasetDetail" + } + } + } + }, + "409": { + "$ref": "#/components/responses/DatasetNameDuplicate" + } + } + }, + "delete": { + "tags": [ + "数据集" + ], + "summary": "删除知识库", + "description": "删除知识库及其所有相关文档和数据。", + "operationId": "deleteDataset", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "要删除的知识库的唯一标识符。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "成功删除数据集。" + } + } + } + }, + "/datasets/{dataset_id}/document/create-by-text": { + "post": { + "tags": [ + "文档" + ], + "summary": "从文本创建文档", + "description": "直接从文本内容在现有知识库中创建新文档。", + "operationId": "createDocumentFromText", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "要添加文档的知识库 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateDocumentByTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "文档创建成功，正在被索引。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentCreationResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/document/create-by-file": { + "post": { + "tags": [ + "文档" + ], + "summary": "从文件创建文档", + "description": "通过上传文件在现有知识库中创建新文档。", + "operationId": "createDocumentFromFile", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "要添加文档的知识库 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "string", + "description": "包含文档元数据和处理规则的 JSON 字符串。详情请参见 `CreateDocumentByFileRequestData` 模式。", + "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\":{\"separator\":\"###\", \"max_tokens\":500}}}}" + }, + "file": { + "type": "string", + "format": "binary", + "description": "要上传的文件。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "文档创建成功，正在被索引。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentCreationResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/FileError" + }, + "413": { + "$ref": "#/components/responses/FileTooLarge" + }, + "415": { + "$ref": "#/components/responses/UnsupportedFileType" + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { + "post": { + "tags": [ + "文档" + ], + "summary": "用文本更新文档", + "description": "使用文本更新现有文档的内容或设置。", + "operationId": "updateDocumentByText", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "包含文档的知识库 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "要更新的文档 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateDocumentByTextRequest" + } + } + } + }, + "responses": { + "200": { + "description": "文档更新成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentCreationResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { + "post": { + "tags": [ + "文档" + ], + "summary": "用文件更新文档", + "description": "通过上传新文件更新现有文档，替换其内容。", + "operationId": "updateDocumentByFile", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "包含文档的知识库 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "要更新的文档 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "string", + "description": "包含可选文档名称和处理规则的 JSON 字符串。请参见 `UpdateDocumentByFileRequestData` 模式。", + "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}" + }, + "file": { + "type": "string", + "format": "binary", + "description": "要上传的新文件。" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "文档更新成功。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentCreationResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{batch}/indexing-status": { + "get": { + "tags": [ + "文档" + ], + "summary": "获取文档嵌入状态（进度）", + "description": "检索文档批次的索引状态，显示嵌入和处理的进度。", + "operationId": "getDocumentIndexingStatus", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "batch", + "in": "path", + "required": true, + "description": "从文档创建端点返回的批次号。", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "批次中文档的索引状态。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/IndexingStatus" + } + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}": { + "get": { + "tags": [ + "文档" + ], + "summary": "获取文档详情", + "description": "检索单个文档的详细信息，包括其处理规则和状态。", + "operationId": "getDocumentDetail", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "metadata", + "in": "query", + "description": "元数据过滤器：`all` 返回所有元数据，`only` 仅返回自定义元数据，`without` 不返回元数据。", + "schema": { + "type": "string", + "enum": [ + "all", + "only", + "without" + ], + "default": "all" + } + } + ], + "responses": { + "200": { + "description": "关于文档的详细信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentDetail" + } + } + } + } + } + }, + "delete": { + "tags": [ + "文档" + ], + "summary": "删除文档", + "description": "从知识库中删除特定文档。", + "operationId": "deleteDocument", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "要删除的文档 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "成功删除文档。" + } + } + } + }, + "/datasets/{dataset_id}/documents": { + "get": { + "tags": [ + "文档" + ], + "summary": "获取知识库的文档列表", + "description": "检索指定知识库中所有文档的分页列表。", + "operationId": "listDocuments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "keyword", + "in": "query", + "description": "在文档名称中搜索的关键词。", + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "分页的页码。", + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页返回的项目数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "文档的分页列表。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DocumentListResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/status/{action}": { + "patch": { + "tags": [ + "文档" + ], + "summary": "更新文档状态", + "description": "执行批量操作以更新一个或多个文档的状态（例如，启用、禁用、归档）。", + "operationId": "batchUpdateDocumentStatus", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "action", + "in": "path", + "required": true, + "description": "对文档执行的操作。", + "schema": { + "type": "string", + "enum": [ + "enable", + "disable", + "archive", + "un_archive" + ] + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "document_ids" + ], + "properties": { + "document_ids": { + "type": "array", + "description": "要执行操作的文档 ID 列表。", + "items": { + "type": "string", + "format": "uuid" + } + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/Success" + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments": { + "post": { + "tags": [ + "段落" + ], + "summary": "向文档添加块", + "description": "向特定文档添加一个或多个新块（段落）。这对于手动添加精心策划的内容很有用。", + "operationId": "createSegments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSegmentsRequest" + } + } + } + }, + "responses": { + "200": { + "description": "新创建的段落列表。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SegmentListResponse" + } + } + } + } + } + }, + "get": { + "tags": [ + "段落" + ], + "summary": "从文档获取块", + "description": "从特定文档检索块（段落）的分页列表。", + "operationId": "listSegments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "keyword", + "in": "query", + "description": "按内容过滤段落的关键词。", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "description": "按索引状态过滤段落。", + "schema": { + "type": "string", + "example": "completed" + } + }, + { + "name": "page", + "in": "query", + "description": "分页的页码。", + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页返回的项目数。", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "段落的分页列表。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SegmentPaginatedResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { + "get": { + "tags": [ + "段落" + ], + "summary": "获取文档中的块详情", + "description": "检索文档中特定块（段落）的详情。", + "operationId": "getSegmentDetail", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "段落的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "关于段落的详细信息。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SegmentDetailResponse" + } + } + } + } + } + }, + "post": { + "tags": [ + "段落" + ], + "summary": "更新文档中的块", + "description": "更新特定块（段落）的内容、关键词或状态。", + "operationId": "updateSegment", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "要更新的段落 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateSegmentRequest" + } + } + } + }, + "responses": { + "200": { + "description": "更新的段落详情。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SegmentDetailResponse" + } + } + } + } + } + }, + "delete": { + "tags": [ + "段落" + ], + "summary": "删除文档中的块", + "description": "从文档中删除特定块（段落）。", + "operationId": "deleteSegment", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "要删除的段落 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "成功删除段落。" + } + } + } + }, + "/datasets/{dataset_id}/retrieve": { + "post": { + "tags": [ + "数据集" + ], + "summary": "从知识库检索块", + "description": "对知识库执行搜索查询以检索最相关的块（段落）。", + "operationId": "retrieveSegments", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "要检索的知识库 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetrieveRequest" + } + } + } + }, + "responses": { + "200": { + "description": "与查询匹配的检索段落列表。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetrieveResponse" + } + } + } + } + } + } + }, + "/workspaces/current/models/model-types/text-embedding": { + "get": { + "tags": [ + "模型" + ], + "summary": "获取可用的嵌入模型", + "description": "获取可用于创建和查询知识库的所有可用文本嵌入模型列表。", + "operationId": "getAvailableEmbeddingModels", + "responses": { + "200": { + "description": "按提供商分组的可用嵌入模型列表。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ModelProvider" + } + } + } + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { + "post": { + "tags": [ + "段落" + ], + "summary": "创建子块", + "description": "使用分层模式在文档中的父段落下创建新的子块。", + "operationId": "createChildChunk", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "父段落的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateChildChunkRequest" + } + } + } + }, + "responses": { + "200": { + "description": "成功创建子块。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChildChunkResponse" + } + } + } + } + } + }, + "get": { + "tags": [ + "段落" + ], + "summary": "获取子块", + "description": "检索特定父段落的子块列表。", + "operationId": "getChildChunks", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "父段落的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "keyword", + "in": "query", + "description": "过滤子块的搜索关键词。", + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "分页的页码。", + "schema": { + "type": "integer", + "default": 1 + } + }, + { + "name": "limit", + "in": "query", + "description": "每页返回的项目数。", + "schema": { + "type": "integer", + "default": 20, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "子块的分页列表。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChildChunkListResponse" + } + } + } + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { + "patch": { + "tags": [ + "段落" + ], + "summary": "更新子块", + "description": "更新特定子块的内容。", + "operationId": "updateChildChunk", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "父段落的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "child_chunk_id", + "in": "path", + "required": true, + "description": "要更新的子块 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateChildChunkRequest" + } + } + } + }, + "responses": { + "200": { + "description": "成功更新子块。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ChildChunkResponse" + } + } + } + } + } + }, + "delete": { + "tags": [ + "段落" + ], + "summary": "删除子块", + "description": "删除特定的子块。", + "operationId": "deleteChildChunk", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "segment_id", + "in": "path", + "required": true, + "description": "父段落的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "child_chunk_id", + "in": "path", + "required": true, + "description": "要删除的子块 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "成功删除子块。" + } + } + } + }, + "/datasets/{dataset_id}/documents/{document_id}/upload-file": { + "get": { + "tags": [ + "文档" + ], + "summary": "获取上传文件", + "description": "检索为文档上传的原始文件信息，包括下载 URL。", + "operationId": "getUploadFile", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "知识库的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "description": "文档的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "上传文件的详情。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UploadFileResponse" + } + } + } + } + } + } + }, + "/datasets/tags": { + "post": { + "tags": [ + "元数据和标签" + ], + "summary": "创建新的知识库类型标签", + "description": "创建可用于分类知识库的新标签。", + "operationId": "createKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["name"], + "properties": { + "name": { + "type": "string", + "description": "新标签的名称。", + "maxLength": 50 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "成功创建标签。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + } + } + } + } + } + }, + "get": { + "tags": [ + "元数据和标签" + ], + "summary": "获取知识库类型标签", + "description": "检索所有可用知识库标签的列表。", + "operationId": "getKnowledgeTags", + "responses": { + "200": { + "description": "标签列表。", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Tag" + } + } + } + } + } + } + }, + "patch": { + "tags": [ + "元数据和标签" + ], + "summary": "修改知识库类型标签名称", + "description": "更新现有标签的名称。", + "operationId": "updateKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["tag_id", "name"], + "properties": { + "tag_id": { + "type": "string", + "description": "要修改的标签 ID。", + "format": "uuid" + }, + "name": { + "type": "string", + "description": "标签的新名称。", + "maxLength": 50 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "成功更新标签。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tag" + } + } + } + } + } + }, + "delete": { + "tags": [ + "元数据和标签" + ], + "summary": "删除知识库类型标签", + "description": "删除标签。标签不得绑定到任何知识库。", + "operationId": "deleteKnowledgeTag", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["tag_id"], + "properties": { + "tag_id": { + "type": "string", + "description": "要删除的标签 ID。", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/Success" + } + } + } + }, + "/datasets/tags/binding": { + "post": { + "tags": [ + "元数据和标签" + ], + "summary": "将数据集绑定到知识库类型标签", + "description": "将一个或多个标签绑定到特定知识库。", + "operationId": "bindTagsToDataset", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["target_id", "tag_ids"], + "properties": { + "target_id": { + "type": "string", + "description": "要绑定标签的数据集 ID。", + "format": "uuid" + }, + "tag_ids": { + "type": "array", + "description": "要绑定的标签 ID 列表。", + "items": { + "type": "string", + "format": "uuid" + } + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/Success" + } + } + } + }, + "/datasets/tags/unbinding": { + "post": { + "tags": [ + "元数据和标签" + ], + "summary": "解绑数据集和知识库类型标签", + "description": "从知识库解绑特定标签。", + "operationId": "unbindTagFromDataset", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["target_id", "tag_id"], + "properties": { + "target_id": { + "type": "string", + "description": "数据集的 ID。", + "format": "uuid" + }, + "tag_id": { + "type": "string", + "description": "要解绑的标签 ID。", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/Success" + } + } + } + }, + "/datasets/{dataset_id}/tags": { + "post": { + "tags": [ + "元数据和标签" + ], + "summary": "查询绑定到数据集的标签", + "description": "检索当前绑定到特定数据集的所有标签。", + "operationId": "queryDatasetTags", + "parameters": [ + { + "name": "dataset_id", + "in": "path", + "required": true, + "description": "数据集的 ID。", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "绑定到数据集的标签列表。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" } + } + } + }, + "total": { + "type": "integer" + } + } + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "ApiKeyAuth": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "API_KEY", + "description": "API-Key 鉴权。所有 API 请求都应在 `Authorization` HTTP Header 中包含您的 API-Key，格式为 `Bearer {API_KEY}`。**强烈建议开发者把 API-Key 放在后端存储，而非分享或者放在客户端存储，以免 API-Key 泄露，导致财产损失。**" + } + }, + "responses": { + "Success": { + "description": "操作成功。", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "string", + "example": "success" + } + } + } + } + } + }, + "FileError": { + "description": "与文件上传相关的错误请求。可能是 `no_file_uploaded` 或 `too_many_files`。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "FileTooLarge": { + "description": "文件大小超出限制。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "UnsupportedFileType": { + "description": "不允许的文件类型。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "DatasetNameDuplicate": { + "description": "数据集名称已存在。", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + }, + "schemas": { + "ErrorResponse": { + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "机器可读的错误代码。" + }, + "message": { + "type": "string", + "description": "人类可读的错误消息。" + }, + "status": { + "type": "integer", + "description": "HTTP 状态码。" + } + }, + "example": { + "code": "no_file_uploaded", + "message": "请上传您的文件。", + "status": 400 + } + }, + "RetrievalModel": { + "type": "object", + "properties": { + "search_method": { + "type": "string", + "description": "用于检索的搜索方法。", + "enum": [ + "hybrid_search", + "semantic_search", + "full_text_search", + "keyword_search" + ] + }, + "reranking_enable": { + "type": "boolean", + "description": "是否启用重新排序模型以改善搜索结果。" + }, + "reranking_mode": { + "type": "object", + "description": "重新排序模型的配置。", + "properties": { + "reranking_provider_name": { + "type": "string", + "description": "重新排序模型的提供商。" + }, + "reranking_model_name": { + "type": "string", + "description": "重新排序模型的名称。" + } + }, + "nullable": true + }, + "top_k": { + "type": "integer", + "description": "返回的顶部匹配结果数量。" + }, + "score_threshold_enabled": { + "type": "boolean", + "description": "是否应用分数阈值来过滤结果。" + }, + "score_threshold": { + "type": "number", + "format": "float", + "description": "结果包含的最低分数。", + "nullable": true + }, + "weights": { + "type": "number", + "format": "float", + "description": "混合搜索模式中语义搜索的权重。", + "nullable": true + } + } + }, + "PreprocessingRule": { + "type": "object", + "description": "文档内容预处理规则。", + "properties": { + "id": { + "type": "string", + "description": "预处理规则的唯一标识符。", + "enum": [ + "remove_extra_spaces", + "remove_urls_emails" + ] + }, + "enabled": { + "type": "boolean", + "description": "此规则是否启用。" + } + } + }, + "SegmentationRule": { + "type": "object", + "description": "将文档内容分割成块的规则。", + "properties": { + "separator": { + "type": "string", + "description": "用于分离段落的自定义分隔符。" + }, + "max_tokens": { + "type": "integer", + "description": "单个段落中允许的最大令牌数。" + } + } + }, + "SubChunkSegmentationRule": { + "type": "object", + "description": "将父块分割为较小子块的规则（用于分层模式）。", + "properties": { + "separator": { + "type": "string", + "description": "子块的分隔符。" + }, + "max_tokens": { + "type": "integer", + "description": "子块的最大令牌长度。" + }, + "chunk_overlap": { + "type": "integer", + "description": "相邻子块之间的重叠令牌数。" + } + } + }, + "ProcessRule": { + "type": "object", + "description": "用于处理文档的规则集，包括清理和分割。", + "properties": { + "mode": { + "type": "string", + "description": "处理模式：automatic、custom 或 hierarchical。", + "enum": [ + "automatic", + "custom", + "hierarchical" + ] + }, + "rules": { + "type": "object", + "description": "要应用的特定规则，当模式为 'custom' 或 'hierarchical' 时使用。", + "properties": { + "pre_processing_rules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PreprocessingRule" + } + }, + "segmentation": { + "$ref": "#/components/schemas/SegmentationRule" + }, + "parent_mode": { + "type": "string", + "description": "分层模式中父块的检索模式。", + "enum": [ + "full-doc", + "paragraph" + ] + }, + "subchunk_segmentation": { + "$ref": "#/components/schemas/SubChunkSegmentationRule" + } + }, + "nullable": true + } + } + }, + "CreateDocumentByTextRequest": { + "type": "object", + "required": [ + "name", + "text" + ], + "properties": { + "name": { + "type": "string", + "description": "文档名称。" + }, + "text": { + "type": "string", + "description": "文档的完整文本内容。" + }, + "indexing_technique": { + "type": "string", + "description": "文档的索引技术。", + "enum": [ + "high_quality", + "economy" + ] + }, + "doc_form": { + "type": "string", + "description": "索引内容的格式。", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ] + }, + "doc_language": { + "type": "string", + "description": "文档的语言，在 Q&A 模式中很重要。", + "example": "中文" + }, + "process_rule": { + "$ref": "#/components/schemas/ProcessRule" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel" + }, + "embedding_model": { + "type": "string", + "description": "要使用的嵌入模型名称。" + }, + "embedding_model_provider": { + "type": "string", + "description": "嵌入模型的提供商。" + } + } + }, + "CreateDocumentByFileRequestData": { + "type": "object", + "description": "从文件创建文档的元数据和规则。", + "properties": { + "original_document_id": { + "type": "string", + "description": "要重新上传或修改的现有文档 ID。", + "format": "uuid" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ] + }, + "doc_form": { + "type": "string", + "enum": [ + "text_model", + "hierarchical_model", + "qa_model" + ] + }, + "doc_language": { + "type": "string", + "example": "中文" + }, + "process_rule": { + "$ref": "#/components/schemas/ProcessRule" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel" + }, + "embedding_model": { + "type": "string" + }, + "embedding_model_provider": { + "type": "string" + } + } + }, + "UpdateDocumentByTextRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "文档的新名称（可选）。" + }, + "text": { + "type": "string", + "description": "文档的新文本内容（可选）。" + }, + "process_rule": { + "$ref": "#/components/schemas/ProcessRule" + } + } + }, + "UpdateDocumentByFileRequestData": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "文档的新名称（可选）。" + }, + "process_rule": { + "$ref": "#/components/schemas/ProcessRule" + } + } + }, + "Document": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "position": { + "type": "integer" + }, + "data_source_type": { + "type": "string" + }, + "data_source_info": { + "type": "object", + "nullable": true + }, + "dataset_process_rule_id": { + "type": "string", + "format": "uuid", + "nullable": true + }, + "name": { + "type": "string" + }, + "created_from": { + "type": "string" + }, + "created_by": { + "type": "string", + "format": "uuid" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "tokens": { + "type": "integer" + }, + "indexing_status": { + "type": "string" + }, + "error": { + "type": "string", + "nullable": true + }, + "enabled": { + "type": "boolean" + }, + "disabled_at": { + "type": "integer", + "format": "int64", + "nullable": true + }, + "disabled_by": { + "type": "string", + "format": "uuid", + "nullable": true + }, + "archived": { + "type": "boolean" + }, + "display_status": { + "type": "string" + }, + "word_count": { + "type": "integer" + }, + "hit_count": { + "type": "integer" + }, + "doc_form": { + "type": "string" + } + } + }, + "DocumentCreationResponse": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/Document" + }, + "batch": { + "type": "string", + "description": "用于跟踪索引进度的批次标识符。" + } + } + }, + "CreateDatasetRequest": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "知识库的名称。" + }, + "description": { + "type": "string", + "description": "知识库的描述（可选）。" + }, + "indexing_technique": { + "type": "string", + "description": "要使用的索引技术。", + "enum": [ + "high_quality", + "economy" + ] + }, + "permission": { + "type": "string", + "description": "知识库的访问权限。", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ] + }, + "provider": { + "type": "string", + "description": "知识库的提供商。", + "enum": [ + "vendor", + "external" + ] + }, + "external_knowledge_api_id": { + "type": "string", + "description": "外部知识 API 的 ID（如果提供商是 'external'）。" + }, + "external_knowledge_id": { + "type": "string", + "description": "外部知识的 ID（如果提供商是 'external'）。" + }, + "embedding_model": { + "type": "string", + "description": "嵌入模型的名称。" + }, + "embedding_model_provider": { + "type": "string", + "description": "嵌入模型的提供商。" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel" + } + } + }, + "Dataset": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string", + "nullable": true + }, + "provider": { + "type": "string" + }, + "permission": { + "type": "string" + }, + "data_source_type": { + "type": "string", + "nullable": true + }, + "indexing_technique": { + "type": "string", + "nullable": true + }, + "app_count": { + "type": "integer" + }, + "document_count": { + "type": "integer" + }, + "word_count": { + "type": "integer" + }, + "created_by": { + "type": "string", + "format": "uuid" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "updated_by": { + "type": "string", + "format": "uuid" + }, + "updated_at": { + "type": "integer", + "format": "int64" + }, + "embedding_model": { + "type": "string", + "nullable": true + }, + "embedding_model_provider": { + "type": "string", + "nullable": true + }, + "embedding_available": { + "type": "boolean", + "nullable": true + } + } + }, + "DatasetListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Dataset" + } + }, + "has_more": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "page": { + "type": "integer" + } + } + }, + "DatasetDetail": { + "allOf": [ + { + "$ref": "#/components/schemas/Dataset" + }, + { + "type": "object", + "properties": { + "retrieval_model_dict": { + "$ref": "#/components/schemas/RetrievalModel" + }, + "tags": { + "type": "array", + "items": { + "type": "object" + } + }, + "doc_form": { + "type": "string", + "nullable": true + } + } + } + ] + }, + "UpdateDatasetRequest": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "知识库的新名称。" + }, + "description": { + "type": "string", + "description": "知识库的新描述。" + }, + "indexing_technique": { + "type": "string", + "enum": [ + "high_quality", + "economy" + ] + }, + "permission": { + "type": "string", + "enum": [ + "only_me", + "all_team_members", + "partial_members" + ] + }, + "embedding_model_provider": { + "type": "string" + }, + "embedding_model": { + "type": "string" + }, + "retrieval_model": { + "$ref": "#/components/schemas/RetrievalModel" + }, + "partial_member_list": { + "type": "array", + "description": "'partial_members' 权限的成员 ID 列表。", + "items": { + "type": "string" + } + } + } + }, + "IndexingStatus": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "indexing_status": { + "type": "string" + }, + "processing_started_at": { + "type": "number", + "format": "float" + }, + "parsing_completed_at": { + "type": "number", + "format": "float" + }, + "cleaning_completed_at": { + "type": "number", + "format": "float" + }, + "splitting_completed_at": { + "type": "number", + "format": "float" + }, + "completed_at": { + "type": "number", + "format": "float", + "nullable": true + }, + "paused_at": { + "type": "number", + "format": "float", + "nullable": true + }, + "error": { + "type": "string", + "nullable": true + }, + "stopped_at": { + "type": "number", + "format": "float", + "nullable": true + }, + "completed_segments": { + "type": "integer" + }, + "total_segments": { + "type": "integer" + } + } + }, + "DocumentListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Document" + } + }, + "has_more": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "page": { + "type": "integer" + } + } + }, + "DocumentDetail": { + "allOf": [ + { + "$ref": "#/components/schemas/Document" + }, + { + "type": "object", + "properties": { + "dataset_process_rule": { + "$ref": "#/components/schemas/ProcessRule" + }, + "document_process_rule": { + "allOf": [ + { + "$ref": "#/components/schemas/ProcessRule" + }, + { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "dataset_id": { + "type": "string" + } + } + } + ] + }, + "indexing_latency": { + "type": "number", + "format": "float", + "nullable": true + }, + "segment_count": { + "type": "integer" + }, + "average_segment_length": { + "type": "integer" + }, + "doc_language": { + "type": "string", + "nullable": true + } + } + } + ] + }, + "Segment": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "position": { + "type": "integer" + }, + "document_id": { + "type": "string", + "format": "uuid" + }, + "content": { + "type": "string" + }, + "answer": { + "type": "string", + "nullable": true + }, + "word_count": { + "type": "integer" + }, + "tokens": { + "type": "integer" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + } + }, + "index_node_id": { + "type": "string" + }, + "index_node_hash": { + "type": "string" + }, + "hit_count": { + "type": "integer" + }, + "enabled": { + "type": "boolean" + }, + "disabled_at": { + "type": "integer", + "format": "int64", + "nullable": true + }, + "disabled_by": { + "type": "string", + "format": "uuid", + "nullable": true + }, + "status": { + "type": "string" + }, + "created_by": { + "type": "string", + "format": "uuid" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "indexing_at": { + "type": "integer", + "format": "int64" + }, + "completed_at": { + "type": "integer", + "format": "int64" + }, + "error": { + "type": "string", + "nullable": true + }, + "stopped_at": { + "type": "integer", + "format": "int64", + "nullable": true + } + } + }, + "CreateSegmentsRequest": { + "type": "object", + "properties": { + "segments": { + "type": "array", + "items": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string", + "description": "块的文本内容（Q&A 模式中为问题）。" + }, + "answer": { + "type": "string", + "description": "答案内容，如果文档处于 Q&A 模式则必需。" + }, + "keywords": { + "type": "array", + "description": "与块关联的关键词。", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "SegmentListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Segment" + } + }, + "doc_form": { + "type": "string" + } + } + }, + "SegmentPaginatedResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/SegmentListResponse" + }, + { + "type": "object", + "properties": { + "has_more": { + "type": "boolean" + }, + "limit": { + "type": "integer" + }, + "total": { + "type": "integer" + }, + "page": { + "type": "integer" + } + } + } + ] + }, + "SegmentDetailResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Segment" + }, + "doc_form": { + "type": "string" + } + } + }, + "UpdateSegmentRequest": { + "type": "object", + "properties": { + "segment": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string" + }, + "answer": { + "type": "string" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + } + }, + "enabled": { + "type": "boolean" + }, + "regenerate_child_chunks": { + "type": "boolean", + "description": "是否重新生成子块（分层模式）。" + } + } + } + } + }, + "RetrieveRequest": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "description": "搜索查询字符串。" + }, + "retrieval_model": { + "allOf": [ + { + "$ref": "#/components/schemas/RetrievalModel" + }, + { + "type": "object", + "properties": { + "metadata_filtering_conditions": { + "type": "object", + "description": "基于元数据过滤结果的条件。", + "properties": { + "logical_operator": { + "type": "string", + "enum": [ + "and", + "or" + ] + }, + "conditions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "元数据字段的名称。" + }, + "comparison_operator": { + "type": "string", + "description": "比较的运算符。" + }, + "value": { + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + } + ], + "nullable": true, + "description": "要比较的值。" + } + } + } + } + } + } + } + } + ] + } + } + }, + "RetrievedSegment": { + "type": "object", + "properties": { + "segment": { + "allOf": [ + { + "$ref": "#/components/schemas/Segment" + }, + { + "type": "object", + "properties": { + "document": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "data_source_type": { + "type": "string" + }, + "name": { + "type": "string" + } + } + } + } + } + ] + }, + "score": { + "type": "number", + "format": "float" + } + } + }, + "RetrieveResponse": { + "type": "object", + "properties": { + "query": { + "type": "object", + "properties": { + "content": { + "type": "string" + } + } + }, + "records": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RetrievedSegment" + } + } + } + }, + "Model": { + "type": "object", + "properties": { + "model": { + "type": "string" + }, + "label": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "model_type": { + "type": "string" + }, + "features": { + "type": "array", + "items": {}, + "nullable": true + }, + "fetch_from": { + "type": "string" + }, + "model_properties": { + "type": "object", + "properties": { + "context_size": { + "type": "integer" + } + } + }, + "deprecated": { + "type": "boolean" + }, + "status": { + "type": "string" + }, + "load_balancing_enabled": { + "type": "boolean" + } + } + }, + "ModelProvider": { + "type": "object", + "properties": { + "provider": { + "type": "string" + }, + "label": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "icon_small": { + "type": "object", + "additionalProperties": { + "type": "string", + "format": "uri" + } + }, + "icon_large": { + "type": "object", + "additionalProperties": { + "type": "string", + "format": "uri" + } + }, + "status": { + "type": "string" + }, + "models": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Model" + } + } + } + }, + "ChildChunk": { + "type": "object", + "description": "表示分层分割中的子块。", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "segment_id": { "type": "string", "format": "uuid" }, + "content": { "type": "string" }, + "word_count": { "type": "integer" }, + "tokens": { "type": "integer" }, + "index_node_id": { "type": "string" }, + "index_node_hash": { "type": "string" }, + "status": { "type": "string" }, + "created_by": { "type": "string", "format": "uuid" }, + "created_at": { "type": "integer", "format": "int64" }, + "indexing_at": { "type": "integer", "format": "int64" }, + "completed_at": { "type": "integer", "format": "int64" }, + "error": { "type": "string", "nullable": true }, + "stopped_at": { "type": "integer", "format": "int64", "nullable": true } + } + }, + "CreateChildChunkRequest": { + "type": "object", + "required": ["content"], + "properties": { + "content": { + "type": "string", + "description": "子块的内容。" + } + } + }, + "UpdateChildChunkRequest": { + "type": "object", + "required": ["content"], + "properties": { + "content": { + "type": "string", + "description": "子块的更新内容。" + } + } + }, + "ChildChunkResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ChildChunk" + } + } + }, + "ChildChunkListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChildChunk" + } + }, + "total": { "type": "integer" }, + "total_pages": { "type": "integer" }, + "page": { "type": "integer" }, + "limit": { "type": "integer" } + } + }, + "UploadFileResponse": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" }, + "size": { "type": "integer" }, + "extension": { "type": "string" }, + "url": { "type": "string", "format": "uri", "description": "文件的预览 URL。" }, + "download_url": { "type": "string", "format": "uri", "description": "文件的下载 URL。" }, + "mime_type": { "type": "string" }, + "created_by": { "type": "string", "format": "uuid" }, + "created_at": { "type": "integer", "format": "int64" } + } + }, + "Tag": { + "type": "object", + "properties": { + "id": { "type": "string", "format": "uuid" }, + "name": { "type": "string" }, + "type": { "type": "string", "example": "knowledge" }, + "binding_count": { "type": "integer" } + } + } + } + } +} \ No newline at end of file