From 40ddb5b21354e6fd851538b5c0b2bb9e2fc8399f Mon Sep 17 00:00:00 2001 From: Riskey <36894937+RiskeyL@users.noreply.github.com> Date: Mon, 23 Mar 2026 17:11:53 +0800 Subject: [PATCH] Update the manage knowledge via api doc (#716) * draft * add zh and ja translations --- .../maintain-dataset-via-api.mdx | 831 +----------------- .../maintain-dataset-via-api.mdx | 723 +-------------- .../maintain-dataset-via-api.mdx | 691 +-------------- 3 files changed, 53 insertions(+), 2192 deletions(-) diff --git a/en/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx b/en/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx index fc13d5ea..0f9fec75 100644 --- a/en/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx +++ b/en/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx @@ -1,828 +1,33 @@ --- title: Manage Knowledge via API +description: Manage your knowledge bases programmatically using the Dify Knowledge Base API --- -> The authentication and invocation methods for the Knowledge Base API are consistent with the Application Service API. However, a single Knowledge Base API token generated has the authority to operate on all visible knowledge bases under the same account. Please pay attention to data security. +Dify provides a complete set of Knowledge Base APIs that let you manage knowledge bases, documents, and chunks programmatically. This is useful for automating data synchronization or integrating knowledge base operations into CI/CD pipelines. -### Advantages of Utilizing Knowledge Base API +API access is enabled by default when you create a knowledge base. To start making API calls, all you need is your API credentials: an endpoint and a key. -Leveraging the API for knowledge base maintenance significantly enhances data processing efficiency. It enables seamless data synchronization via command-line interfaces, facilitating automated operations instead of manipulating the user interface. + +A single Knowledge Base API key has access to **all visible knowledge bases** under the same account. Handle your credentials carefully to avoid unintended data exposure. + -Key advantages include: +## Get Your API Endpoint and Key -* Automated Synchronization: Enables seamless integration between data systems and the Dify knowledge base, fostering efficient workflow construction. -* Comprehensive Management: Offers functionalities such as knowledge base listing, document enumeration, and detailed querying, facilitating the development of custom data management interfaces. -* Flexible Content Ingestion: Accommodates both plain text and file upload methodologies, supporting batch operations for addition and modification of content chunks. -* Enhanced Productivity: Minimizes manual data handling requirements, thereby optimizing the overall user experience on the Dify platform. +Navigate to **Knowledge** in Dify. In the top-right corner, click **Service API** to open the API configuration panel. From here you can: -### How to Use +- Get the Service API endpoint. This is the base URL for all Knowledge Base API requests. +- Click **API Key** to create new keys and manage existing ones. -Navigate to the knowledge base page, and you can switch to the **API ACCESS** page from the left navigation. On this page, you can view the dataset API documentation provided by Dify and manage the credentials for accessing the dataset API in **API Keys**. + + Store your API key securely on the server side. Never expose it in client-side code or public repositories. + -![Knowledge API Document](https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/knowledge-base/knowledge-and-documents-maintenance/2848fc9fc3a7f641f16eee11ed6c6223.png) +## Manage API Access for a Knowledge Base -### API Requesting Examples +Every knowledge base is accessible via the Service API by default. -#### **Create a document from text** +If you want to restrict API access to a specific knowledge base, open it, then click **API Access** in the bottom-left corner and toggle it off. -This api is based on an existing Knowledge and creates a new document through text based on this Knowledge. +## API Reference -Request example: - -```json -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create_by_text' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"name": "text","text": "text","indexing_technique": "high_quality","process_rule": {"mode": "automatic"}}' -``` - -Response example: - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "text.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695690280, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "" -} -``` - -#### Create a Document from a file - -This API is based on an existing knowledge and creates a new document through a file based on this knowledge. - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create-by-file' \ ---header 'Authorization: Bearer {api_key}' \ ---form 'data="{"indexing_technique":"high_quality","process_rule":{"rules":{"pre_processing_rules":[{"id":"remove_extra_spaces","enabled":true},{"id":"remove_urls_emails","enabled":true}],"segmentation":{"separator":"###","max_tokens":500}},"mode":"custom"}}";type=text/plain' \ ---form 'file=@"/path/to/file"' -``` - -```bash -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "Dify.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695308667, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "" -} - -``` - -#### Create Documents from a File - -This api is based on an existing Knowledge and creates a new document through a file based on this Knowledge. - -Request example: - -```json -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create-by-file' \ ---header 'Authorization: Bearer {api_key}' \ ---form 'data="{"indexing_technique":"high_quality","process_rule":{"rules":{"pre_processing_rules":[{"id":"remove_extra_spaces","enabled":true},{"id":"remove_urls_emails","enabled":true}],"segmentation":{"separator":"###","max_tokens":500}},"mode":"custom"}}";type=text/plain' \ ---form 'file=@"/path/to/file"' -``` - -Response example: - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "Dify.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695308667, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "" -} - -``` - -#### Create an Empty Knowledge Base - - - Only used to create an empty knowledge base. - - -Request example: - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"name": "name", "permission": "only_me"}' -``` - -Response example: - -```json -{ - "id": "", - "name": "name", - "description": null, - "provider": "vendor", - "permission": "only_me", - "data_source_type": null, - "indexing_technique": null, - "app_count": 0, - "document_count": 0, - "word_count": 0, - "created_by": "", - "created_at": 1695636173, - "updated_by": "", - "updated_at": 1695636173, - "embedding_model": null, - "embedding_model_provider": null, - "embedding_available": null -} -``` - -#### Get Knowledge Base List - -Request example: - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets?page=1&limit=20' \ ---header 'Authorization: Bearer {api_key}' -``` - -Response example: - -```json -{ - "data": [ - { - "id": "", - "name": "name", - "description": "desc", - "permission": "only_me", - "data_source_type": "upload_file", - "indexing_technique": "", - "app_count": 2, - "document_count": 10, - "word_count": 1200, - "created_by": "", - "created_at": "", - "updated_by": "", - "updated_at": "" - }, - ... - ], - "has_more": true, - "limit": 20, - "total": 50, - "page": 1 -} -``` - -#### Delete a Knowledge Base - -Request example: - -```json -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}' \ ---header 'Authorization: Bearer {api_key}' -``` - -Response example: - -```json -204 No Content -``` - -#### Update a Document with Text - -This api is based on an existing Knowledge and updates the document through text based on this Knowledge - -Request example: - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update_by_text' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"name": "name","text": "text"}' -``` - -Response example: - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "name.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695308667, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "" -} -``` - -#### Update a document with a file - -This api is based on an existing Knowledge, and updates documents through files based on this Knowledge. - -Request example: - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-file' \ ---header 'Authorization: Bearer {api_key}' \ ---form 'data="{"name":"Dify","indexing_technique":"high_quality","process_rule":{"rules":{"pre_processing_rules":[{"id":"remove_extra_spaces","enabled":true},{"id":"remove_urls_emails","enabled":true}],"segmentation":{"separator":"###","max_tokens":500}},"mode":"custom"}}";type=text/plain' \ ---form 'file=@"/path/to/file"' -``` - -Response example: - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "Dify.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695308667, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "20230921150427533684" -} -``` - -#### Get Document Embedding Status (Progress) - -Request example: - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{batch}/indexing-status' \ ---header 'Authorization: Bearer {api_key}' -``` - -Response example: - -```json -{ - "data":[{ - "id": "", - "indexing_status": "indexing", - "processing_started_at": 1681623462.0, - "parsing_completed_at": 1681623462.0, - "cleaning_completed_at": 1681623462.0, - "splitting_completed_at": 1681623462.0, - "completed_at": null, - "paused_at": null, - "error": null, - "stopped_at": null, - "completed_segments": 24, - "total_segments": 100 - }] -} -``` - -#### Delete a Document - -Request example: - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}' \ ---header 'Authorization: Bearer {api_key}' -``` - -Response example: - -```bash -{ - "result": "success" -} -``` - -#### Get the Document List of a Knowledge Base - -Request example: - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents' \ ---header 'Authorization: Bearer {api_key}' -``` - -Response example: - -```json -{ - "data": [ - { - "id": "", - "position": 1, - "data_source_type": "file_upload", - "data_source_info": null, - "dataset_process_rule_id": null, - "name": "dify", - "created_from": "", - "created_by": "", - "created_at": 1681623639, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false - }, - ], - "has_more": false, - "limit": 20, - "total": 9, - "page": 1 -} -``` - -#### Add Chunks to a Document - -Request example: - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"segments": [{"content": "1","answer": "1","keywords": ["a"]}]}' -``` - -Response example: - -```json -{ - "data": [{ - "id": "", - "position": 1, - "document_id": "", - "content": "1", - "answer": "1", - "word_count": 25, - "tokens": 0, - "keywords": [ - "a" - ], - "index_node_id": "", - "index_node_hash": "", - "hit_count": 0, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "status": "completed", - "created_by": "", - "created_at": 1695312007, - "indexing_at": 1695312007, - "completed_at": 1695312007, - "error": null, - "stopped_at": null - }], - "doc_form": "text_model" -} - -``` - -#### Get Chunks from a Document - -Request example: - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' -``` - -Response example: - -```bash -{ - "data": [{ - "id": "", - "position": 1, - "document_id": "", - "content": "1", - "answer": "1", - "word_count": 25, - "tokens": 0, - "keywords": [ - "a" - ], - "index_node_id": "", - "index_node_hash": "", - "hit_count": 0, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "status": "completed", - "created_by": "", - "created_at": 1695312007, - "indexing_at": 1695312007, - "completed_at": 1695312007, - "error": null, - "stopped_at": null - }], - "doc_form": "text_model" -} -``` - -#### Delete a Chunk in a Document - -Request example: - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' -``` - -Response example: - -```bash -{ - "result": "success" -} -``` - -#### Update a Chunk in a Document - -Request example: - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json'\ ---data-raw '{"segment": {"content": "1","answer": "1", "keywords": ["a"], "enabled": false}}' -``` - -Response example: - -```bash -{ - "data": [{ - "id": "", - "position": 1, - "document_id": "", - "content": "1", - "answer": "1", - "word_count": 25, - "tokens": 0, - "keywords": [ - "a" - ], - "index_node_id": "", - "index_node_hash": "", - "hit_count": 0, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "status": "completed", - "created_by": "", - "created_at": 1695312007, - "indexing_at": 1695312007, - "completed_at": 1695312007, - "error": null, - "stopped_at": null - }], - "doc_form": "text_model" -} -``` - -#### Retrieve Chunks from a Knowledge Base - -Request example: - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/retrieve' \ ---header 'Authorization: Bearer {api_key}'\ ---header 'Content-Type: application/json'\ ---data-raw '{ - "query": "test", - "retrieval_model": { - "search_method": "keyword_search", - "reranking_enable": false, - "reranking_mode": null, - "reranking_model": { - "reranking_provider_name": "", - "reranking_model_name": "" - }, - "weights": null, - "top_k": 1, - "score_threshold_enabled": false, - "score_threshold": null - } -}' -``` - -Response example: - -```bash -{ - "query": { - "content": "test" - }, - "records": [ - { - "segment": { - "id": "7fa6f24f-8679-48b3-bc9d-bdf28d73f218", - "position": 1, - "document_id": "a8c6c36f-9f5d-4d7a-8472-f5d7b75d71d2", - "content": "Operation guide", - "answer": null, - "word_count": 847, - "tokens": 280, - "keywords": [ - "install", - "java", - "base", - "scripts", - "jdk", - "manual", - "internal", - "opens", - "add", - "vmoptions" - ], - "index_node_id": "39dd8443-d960-45a8-bb46-7275ad7fbc8e", - "index_node_hash": "0189157697b3c6a418ccf8264a09699f25858975578f3467c76d6bfc94df1d73", - "hit_count": 0, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "status": "completed", - "created_by": "dbcb1ab5-90c8-41a7-8b78-73b235eb6f6f", - "created_at": 1728734540, - "indexing_at": 1728734552, - "completed_at": 1728734584, - "error": null, - "stopped_at": null, - "document": { - "id": "a8c6c36f-9f5d-4d7a-8472-f5d7b75d71d2", - "data_source_type": "upload_file", - "name": "readme.txt", - "doc_type": null - } - }, - "score": 3.730463140527718e-05, - "tsne_position": null - } - ] -} -``` - -#### Add Metadata Fields to the Knowledge Base - -Request example: - -```bash -curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer {api_key}' \ ---data '{ - "type":"string", - "name":"test" -}' -``` - -Response example: - -```json -{ - "id": "9f63c91b-d60e-4142-bb0c-c81a54dc2db5", - "type": "string", - "name": "test" -} -``` - -#### Update Metadata Fields in the Knowledge Base - -Request example: - -```bash -curl --location --request PATCH 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/{metadata_id}' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json'\ ---data-raw '{"name": "test"}' -``` - -Response example: - -```json -{ - "id": "abc", - "type": "string", - "name": "test", -} -``` - -#### Delete Metadata Fields in the Knowledge Base - -Request example: - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/{metadata_id}' \ ---header 'Authorization: Bearer {api_key}' -``` - -Response example: - -```json -200 success -``` - -#### Enable/Disable Built-in Fields in the Knowledge Base - -Request example: - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/built-in/{action}' \ ---header 'Authorization: Bearer {api_key}' -``` - -Response example: - -```json -200 success -``` - -#### Modify Metadata for a Single Document (Assignment) - -Request example: - -```bash -curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer {api_key}' ---data '{ - "operation_data":[ - { - "document_id": "3e928bc4-65ea-4201-87c8-cbcc5871f525", - "metadata_list": [ - { - "id": "1887f5ec-966f-4c93-8c99-5ad386022f46", - "value": "dify", - "name": "test" - } - ] - } - ] -}' -``` - -Response example: - -```json -200 success -``` - -#### Metadata List of the Dataset - -Request example: - -```bash -curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata' \ ---header 'Authorization: Bearer {api_key}' -``` - -Response example: - -```json -{ - "doc_metadata": [ - { - "id": "550e8400-e29b-41d4-a716-446655440000", - "type": "string", - "name": "title", - "use_count": 42 - }, - { - "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", - "type": "number", - "name": "price", - "use_count": 28 - }, - { - "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c9", - "type": "time", - "name": "created_at", - "use_count": 35 - } - ], - "built_in_field_enabled": true -} -``` - -### Error message - -Response example: - -```bash - { - "code": "no_file_uploaded", - "message": "Please upload your file.", - "status": 400 - } - -``` - -| code | status | message | -| ----------------------------- | ------ | -------------------------------------------------------------------------------------------- | -| no\_file\_uploaded | 400 | Please upload your file. | -| too\_many\_files | 400 | Only one file is allowed. | -| file\_too\_large | 413 | File size exceeded. | -| unsupported\_file\_type | 415 | File type not allowed. Supported format: txt, markdown, md, pdf, html, html, xlsx, docx, csv | -| high\_quality\_dataset\_only | 400 | Current operation only supports 'high-quality' datasets. | -| dataset\_not\_initialized | 400 | The dataset is still being initialized or indexing. Please wait a moment. | -| archived\_document\_immutable | 403 | The archived document is not editable. | -| dataset\_name\_duplicate | 409 | The dataset name already exists. Please modify your dataset name. | -| invalid\_action | 400 | Invalid action. | -| document\_already\_finished | 400 | The document has been processed. Please refresh the page or go to the document details. | -| document\_indexing | 400 | The document is being processed and cannot be edited. | -| invalid\_metadata | 400 | The metadata content is incorrect. Please check and verify. | +See the [Knowledge Base API Reference](https://docs.dify.ai/api-reference/knowledge-bases/list-knowledge-bases) for the complete list of endpoints, request/response schemas, error codes, and interactive examples. \ No newline at end of file diff --git a/ja/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx b/ja/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx index c48c7922..faaba74d 100644 --- a/ja/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx +++ b/ja/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx @@ -1,718 +1,33 @@ --- -title: APIを活用したナレッジベースのメンテナンス +title: APIによるナレッジベース管理 +description: Dify ナレッジベース API を使用してナレッジベースをプログラムで管理する --- - ⚠️ このドキュメントはAIによって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api)を参照してください。 +Dify は、ナレッジベース、ドキュメント、チャンクをプログラムで管理するための完全なナレッジベース API セットを提供しています。データ同期の自動化や、ナレッジベース操作の CI/CD パイプラインへの統合に活用できます。 -> 認証や呼び出し方法はサービスAPIと同様ですが、生成される各ナレッジベースAPIトークンには、現在のアカウントでアクセス可能なすべてのナレッジベースを操作する権限が付与されています。データの安全性には十分ご注意ください。 +ナレッジベースを作成すると、API アクセスはデフォルトで有効になります。API 呼び出しを開始するには、エンドポイントとキーの API 認証情報のみが必要です。 -## ナレッジベースAPI活用のメリット + +1つのナレッジベース API キーで、同一アカウント配下の**すべてのアクセス可能なナレッジベース**を操作できます。意図しないデータ漏洩を防ぐため、認証情報は適切に管理してください。 + -APIによるナレッジベース管理はデータ処理効率を飛躍的に向上させます。コマンドラインからのデータ同期や自動化操作を容易に実現でき、UI操作の煩雑さから解放されます。 +## API エンドポイントとキーの取得 -主なメリット： +Dify で**ナレッジベース**ページに移動します。右上の **サービス API** をクリックして API 設定パネルを開きます。ここでは以下の操作が可能です： -* **自動同期**: データシステムとDifyナレッジベースをシームレスに連携し、効率的なワークフローを構築。 -* **総合管理**: ナレッジベースリスト、ドキュメントリスト、詳細検索機能を提供し、カスタム管理インターフェースの構築が可能。 -* **柔軟なアップロード**: テキスト直接入力とファイルアップロードを両方サポート、チャンク単位の一括操作に対応。 -* **生産性向上**: 手動作業時間を削減し、Difyプラットフォームの利用体験を最適化。 +- サービス API エンドポイントを取得します。これはすべてのナレッジベース API リクエストのベース URL です。 +- **API キー** をクリックして、新しいキーの作成や既存キーの管理を行います。 -## 使用方法 + + API キーはサーバー側で安全に保管してください。クライアントサイドのコードや公開リポジトリには絶対に公開しないでください。 + -ナレッジベース管理画面左側ナビゲーションの**API**ページにアクセス。APIドキュメントの閲覧や、**APIキー**による認証情報の管理が可能です。 +## ナレッジベースの API アクセス管理 -## API呼び出しの例 +すべてのナレッジベースは、デフォルトでサービス API 経由でアクセス可能です。 -### テクストを通してドキュメントを作成する +特定のナレッジベースの API アクセスを制限するには、そのナレッジベースを開き、左下の **API アクセス** をクリックしてオフに切り替えます。 -入力例： +## API リファレンス -```json -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create-by-text' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"name": "text","text": "text","indexing_technique": "high_quality","process_rule": {"mode": "automatic"}}' -``` - -出力例： - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "text.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695690280, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "" -} -``` - -### ファイルを通してドキュメントを作成する - -入力例： - -```json -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create_by_file' \ ---header 'Authorization: Bearer {api_key}' \ ---form 'data="{"indexing_technique":"high_quality","process_rule":{"rules":{"pre_processing_rules":[{"id":"remove_extra_spaces","enabled":true},{"id":"remove_urls_emails","enabled":true}],"segmentation":{"separator":"###","max_tokens":500}},"mode":"custom"}}";type=text/plain' \ ---form 'file=@"/path/to/file"' -``` - -出力例： - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "Dify.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695308667, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "" -} -``` - -### 空白のナレッジベースを作成する - - - 空のデータセットを作成するためだけに使用 - - -入力例： - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"name": "name", "permission": "only_me"}' -``` - -出力例： - -```json -{ - "id": "", - "name": "name", - "description": null, - "provider": "vendor", - "permission": "only_me", - "data_source_type": null, - "indexing_technique": null, - "app_count": 0, - "document_count": 0, - "word_count": 0, - "created_by": "", - "created_at": 1695636173, - "updated_by": "", - "updated_at": 1695636173, - "embedding_model": null, - "embedding_model_provider": null, - "embedding_available": null -} -``` - -### ナレッジベースリスト - -入力例： - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets?page=1&limit=20' \ ---header 'Authorization: Bearer {api_key}' -``` - -出力例： - -```json -{ - "data": [ - { - "id": "", - "name": "ナレッジベースの名前", - "description": "情報説明", - "permission": "only_me", - "data_source_type": "upload_file", - "indexing_technique": "", - "app_count": 2, - "document_count": 10, - "word_count": 1200, - "created_by": "", - "created_at": "", - "updated_by": "", - "updated_at": "" - }, - ... - ], - "has_more": true, - "limit": 20, - "total": 50, - "page": 1 -} -``` - -### ナレッジベースの削除 - -入力例： - -```json -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}' \ ---header 'Authorization: Bearer {api_key}' -``` - -出力例： - -```json -204 No Content -``` - -### テクストを通してドキュメントを更新する - -このAPIは存在しているナレッジベースにしか使えます。 - -入力例： - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update_by_text' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"name": "name","text": "text"}' -``` - -出力例： - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "name.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695308667, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "" -} -``` - -### ファイルを通してドキュメントを更新する - -このAPIは存在しているナレッジベースにしか使えます。 - -入力例： - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update_by_file' \ ---header 'Authorization: Bearer {api_key}' \ ---form 'data="{"name":"Dify","indexing_technique":"high_quality","process_rule":{"rules":{"pre_processing_rules":[{"id":"remove_extra_spaces","enabled":true},{"id":"remove_urls_emails","enabled":true}],"segmentation":{"separator":"###","max_tokens":500}},"mode":"custom"}}";type=text/plain' \ ---form 'file=@"/path/to/file"' -``` - -出力例： - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "Dify.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695308667, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "20230921150427533684" -} -``` - -### ドキュメント埋め込みステータス(進捗状況)の取得 - -入力例： - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{batch}/indexing-status' \ ---header 'Authorization: Bearer {api_key}' -``` - -出力例： - -```json -{ - "data":[{ - "id": "", - "indexing_status": "indexing", - "processing_started_at": 1681623462.0, - "parsing_completed_at": 1681623462.0, - "cleaning_completed_at": 1681623462.0, - "splitting_completed_at": 1681623462.0, - "completed_at": null, - "paused_at": null, - "error": null, - "stopped_at": null, - "completed_segments": 24, - "total_segments": 100 - }] -} -``` - -### ドキュメント埋め込みステータス(進捗状況)の取得 - -入力例： - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{batch}/indexing-status' \ ---header 'Authorization: Bearer {api_key}' -``` - -出力例： - -```json -{ - "data":[{ - "id": "", - "indexing_status": "indexing", - "processing_started_at": 1681623462.0, - "parsing_completed_at": 1681623462.0, - "cleaning_completed_at": 1681623462.0, - "splitting_completed_at": 1681623462.0, - "completed_at": null, - "paused_at": null, - "error": null, - "stopped_at": null, - "completed_segments": 24, - "total_segments": 100 - }] -} -``` - -### ドキュメントの削除 - -入力例： - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}' \ ---header 'Authorization: Bearer {api_key}' -``` - -出力例： - -```bash -{ - "result": "success" -} -``` - -### ナレッジベースのドキュメントのリスト - -入力例： - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents' \ ---header 'Authorization: Bearer {api_key}' -``` - -出力例： - -```json -{ - "data": [ - { - "id": "", - "position": 1, - "data_source_type": "file_upload", - "data_source_info": null, - "dataset_process_rule_id": null, - "name": "dify", - "created_from": "", - "created_by": "", - "created_at": 1681623639, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false - }, - ], - "has_more": false, - "limit": 20, - "total": 9, - "page": 1 -} -``` - -### 新しセグメントを増加 - -入力例： - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"segments": [{"content": "1","answer": "1","keywords": ["a"]}]}' -``` - -出力例： - -```json -{ - "data": [{ - "id": "", - "position": 1, - "document_id": "", - "content": "1", - "answer": "1", - "word_count": 25, - "tokens": 0, - "keywords": [ - "a" - ], - "index_node_id": "", - "index_node_hash": "", - "hit_count": 0, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "status": "completed", - "created_by": "", - "created_at": 1695312007, - "indexing_at": 1695312007, - "completed_at": 1695312007, - "error": null, - "stopped_at": null - }], - "doc_form": "text_model" -} - -``` - -### ドキュメントのセグメントを見つける - -入力例： - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' -``` - -出力例： - -```bash -{ - "data": [{ - "id": "", - "position": 1, - "document_id": "", - "content": "1", - "answer": "1", - "word_count": 25, - "tokens": 0, - "keywords": [ - "a" - ], - "index_node_id": "", - "index_node_hash": "", - "hit_count": 0, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "status": "completed", - "created_by": "", - "created_at": 1695312007, - "indexing_at": 1695312007, - "completed_at": 1695312007, - "error": null, - "stopped_at": null - }], - "doc_form": "text_model" -} -``` - -### ドキュメントのセグメントの削除 - -入力例： - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' -``` - -出力例： - -```bash -{ - "result": "success" -} -``` - -### ドキュメントのセグメントの更新 - -入力例： - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json'\ ---data-raw '{"segment": {"content": "1","answer": "1", "keywords": ["a"], "enabled": false}}' -``` - -出力例： - -```bash -{ - "data": [{ - "id": "", - "position": 1, - "document_id": "", - "content": "1", - "answer": "1", - "word_count": 25, - "tokens": 0, - "keywords": [ - "a" - ], - "index_node_id": "", - "index_node_hash": "", - "hit_count": 0, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "status": "completed", - "created_by": "", - "created_at": 1695312007, - "indexing_at": 1695312007, - "completed_at": 1695312007, - "error": null, - "stopped_at": null - }], - "doc_form": "text_model" -} -``` - -### ナレッジベースのメタデータフィールドを追加する - -入力例： - -```bash -curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer {api_key}' \ ---data '{ - "type":"string", - "name":"test" -}' -``` - -出力例： - -```json -{ - "id": "9f63c91b-d60e-4142-bb0c-c81a54dc2db5", - "type": "string", - "name": "test" -} -``` - -### ナレッジベースのメタデータフィールドを更新する - -入力例： - -```bash -curl --location --request PATCH 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/{metadata_id}' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json'\ ---data-raw '{"name": "test"}' -``` - -出力例： - -```json -{ - "id": "abc", - "type": "string", - "name": "test", -} -``` - -### ナレッジベースのメタデータフィールドを削除する - -入力例： - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/{metadata_id}' \ ---header 'Authorization: Bearer {api_key}' -``` - -出力例： - -```json -200 success -``` - -### ナレッジベースのメタデータにある組み込みフィールドを有効化/無効化する - -入力例： - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/built-in/{action}' \ ---header 'Authorization: Bearer {api_key}' -``` - -出力例： - -```json -200 success -``` - -### ドキュメントのメタデータを修正する（値の割り当て） - -入力例： - -```bash -curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer {api_key}' ---data '{ - "operation_data":[ - { - "document_id": "3e928bc4-65ea-4201-87c8-cbcc5871f525", - "metadata_list": [ - { - "id": "1887f5ec-966f-4c93-8c99-5ad386022f46", - "value": "dify", - "name": "test" - } - ] - } - ] -}' -``` - -出力例： - -```json -200 success -``` - -### データセットのメタデータリスト - -入力例： - -```bash -curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata' \ ---header 'Authorization: Bearer {api_key}' -``` - -出力例： - -```json -{ - "doc_metadata": [ - { - "id": "550e8400-e29b-41d4-a716-446655440000", - "type": "string", - "name": "title", - "use_count": 42 - }, - { - "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", - "type": "number", - "name": "price", - "use_count": 28 - }, - { - "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c9", - "type": "time", - "name": "created_at", - "use_count": 35 - } - ], - "built_in_field_enabled": true -} -``` - -### エラーメッセージ - -| エラーメッセージ | エラーコード | 理由 | -| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------ | -| no\_file\_uploaded | 400 | ファイルをアップロードしてください | -| too\_many\_files | 400 | 1つのファイルのみアップロードできます | -| file\_too\_large | 413 | ファイルサイズが制限を超えています | -| unsupported\_file\_type | 415 | サポートされていないファイルタイプです。現在、以下の形式のみをサポートしています：`txt`、 `markdown`、 `md`、 `pdf`、 `html`、 `xlsx`、 `docx`、 `csv` | -| high\_quality\_dataset\_only | 400 | 現在の操作は「高品質」のナレッジベースのみをサポートしています | -| dataset\_not\_initialized | 400 | ナレッジベースはまだ初期化中またはインデックス中です。お待ちください | -| archived\_document\_immutable | 403 | アーカイブされたドキュメントは編集できません | -| dataset\_name\_duplicate | 409 | ナレッジベース名がすでに存在します。ナレッジベース名を変更してください | -| invalid\_action | 400 | 無効な操作です | -| document\_already\_finished | 400 | ドキュメントの処理がすでに完了しています。ページを更新するか、ドキュメントの詳細を確認してください | -| document\_indexing | 400 | ドキュメントが処理中のため、編集できません | -| invalid\_metadata | 400 | メタデータの内容が正しくありません。確認して検証してください | +エンドポイントの完全なリスト、リクエスト/レスポンスのスキーマ、エラーコード、インタラクティブな例については、[ナレッジベース API リファレンス](https://docs.dify.ai/api-reference/データセット/ナレッジベースリストを取得)をご覧ください。 diff --git a/zh/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx b/zh/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx index fbda5141..19e60cb0 100644 --- a/zh/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx +++ b/zh/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api.mdx @@ -1,692 +1,33 @@ --- title: 通过 API 维护知识库 +description: 使用 Dify 知识库 API 以编程方式管理知识库 --- - ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考[英文原版](/en/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api)。 +Dify 提供了一套完整的知识库 API，可以通过编程方式管理知识库、文档和分段。这对于自动化数据同步或将知识库操作集成到 CI/CD 流程中非常有用。 -> 鉴权、调用方式与应用 Service API 保持一致，不同之处在于，所生成的单个知识库 API token 具备操作当前账号下所有可见知识库的权限，请注意数据安全。 - -### 使用知识库 API 的优势 - -通过 API 维护知识库可大幅提升数据处理效率，你可以通过命令行轻松同步数据，实现自动化操作，而无需在用户界面进行繁琐操作。 - -主要优势包括: - -* 自动同步: 将数据系统与 Dify 知识库无缝对接，构建高效工作流程； -* 全面管理: 提供知识库列表，文档列表及详情查询等功能，方便你自建数据管理界面； -* 灵活上传: 支持纯文本和文件上传方式,可针对分段（Chunks）内容的批量新增和修改操作； -* 提高效率: 减少手动处理时间，提升 Dify 平台使用体验。 - -### 如何使用 - -进入知识库页面，在左侧的导航中切换至 **API** 页面。在该页面中你可以查看 Dify 提供的知识库 API 文档，并可以在 **API 密钥** 中管理可访问知识库 API 的凭据。 - -![](https://assets-docs.dify.ai/2025/03/82ef51dc6886fb8301a2b85a920b12d0.png) - -### API 调用示例 - -#### 通过文本创建文档 - -输入示例： - -```json -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create_by_text' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"name": "text","text": "text","indexing_technique": "high_quality","process_rule": {"mode": "automatic"}}' -``` - -输出示例： - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "text.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695690280, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "" -} -``` - -#### 通过文件创建文档 - -输入示例： - -```json -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create_by_file' \ ---header 'Authorization: Bearer {api_key}' \ ---form 'data="{"indexing_technique":"high_quality","process_rule":{"rules":{"pre_processing_rules":[{"id":"remove_extra_spaces","enabled":true},{"id":"remove_urls_emails","enabled":true}],"segmentation":{"separator":"###","max_tokens":500}},"mode":"custom"}}";type=text/plain' \ ---form 'file=@"/path/to/file"' -``` - -输出示例： - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "Dify.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695308667, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "" -} - -``` - -#### **创建空知识库** +创建知识库时，API 访问默认开启。要开始调用 API，你只需要 API 凭据：一个端点和一个密钥。 - 仅用来创建空知识库 +单个知识库 API 密钥可以访问同一账号下的**所有可见知识库**。请妥善保管凭据，避免意外的数据泄露。 -输入示例： +## 获取 API 端点和密钥 -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"name": "name", "permission": "only_me"}' -``` +在 Dify 中进入**知识库**页面。点击右上角的 **服务 API** 打开 API 配置面板。在这里你可以： -输出示例： +- 获取服务 API 端点，即所有知识库 API 请求的基础 URL。 +- 点击 **API 密钥** 创建新密钥并管理已有密钥。 -```json -{ - "id": "", - "name": "name", - "description": null, - "provider": "vendor", - "permission": "only_me", - "data_source_type": null, - "indexing_technique": null, - "app_count": 0, - "document_count": 0, - "word_count": 0, - "created_by": "", - "created_at": 1695636173, - "updated_by": "", - "updated_at": 1695636173, - "embedding_model": null, - "embedding_model_provider": null, - "embedding_available": null -} -``` + + 请将 API 密钥安全存储在服务端，切勿在客户端代码或公开仓库中暴露。 + -#### **知识库列表** +## 管理知识库的 API 访问权限 -输入示例： +每个知识库默认都可通过服务 API 访问。 -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets?page=1&limit=20' \ ---header 'Authorization: Bearer {api_key}' -``` +如果需要限制某个知识库的 API 访问，打开该知识库，点击左下角的 **访问 API** 并将其关闭。 -输出示例： +## API 参考 -```json -{ - "data": [ - { - "id": "", - "name": "知识库名称", - "description": "描述信息", - "permission": "only_me", - "data_source_type": "upload_file", - "indexing_technique": "", - "app_count": 2, - "document_count": 10, - "word_count": 1200, - "created_by": "", - "created_at": "", - "updated_by": "", - "updated_at": "" - }, - ... - ], - "has_more": true, - "limit": 20, - "total": 50, - "page": 1 -} -``` - -#### 删除知识库 - -输入示例： - -```json -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}' \ ---header 'Authorization: Bearer {api_key}' -``` - -输出示例： - -```json -204 No Content -``` - -#### 通过文本更新文档 - -此接口基于已存在知识库，在此知识库的基础上通过文本更新文档 - -输入示例： - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update_by_text' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"name": "name","text": "text"}' -``` - -输出示例： - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "name.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695308667, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "" -} -``` - -#### 通过文件更新文档 - -此接口基于已存在知识库，在此知识库的基础上通过文件更新文档的操作。 - -输入示例： - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update_by_file' \ ---header 'Authorization: Bearer {api_key}' \ ---form 'data="{"name":"Dify","indexing_technique":"high_quality","process_rule":{"rules":{"pre_processing_rules":[{"id":"remove_extra_spaces","enabled":true},{"id":"remove_urls_emails","enabled":true}],"segmentation":{"separator":"###","max_tokens":500}},"mode":"custom"}}";type=text/plain' \ ---form 'file=@"/path/to/file"' -``` - -输出示例： - -```json -{ - "document": { - "id": "", - "position": 1, - "data_source_type": "upload_file", - "data_source_info": { - "upload_file_id": "" - }, - "dataset_process_rule_id": "", - "name": "Dify.txt", - "created_from": "api", - "created_by": "", - "created_at": 1695308667, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false, - "display_status": "queuing", - "word_count": 0, - "hit_count": 0, - "doc_form": "text_model" - }, - "batch": "20230921150427533684" -} -``` - - -#### **获取文档嵌入状态（进度）** - -输入示例： - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{batch}/indexing-status' \ ---header 'Authorization: Bearer {api_key}' -``` - -输出示例： - -```json -{ - "data":[{ - "id": "", - "indexing_status": "indexing", - "processing_started_at": 1681623462.0, - "parsing_completed_at": 1681623462.0, - "cleaning_completed_at": 1681623462.0, - "splitting_completed_at": 1681623462.0, - "completed_at": null, - "paused_at": null, - "error": null, - "stopped_at": null, - "completed_segments": 24, - "total_segments": 100 - }] -} -``` - -#### **删除文档** - -输入示例： - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}' \ ---header 'Authorization: Bearer {api_key}' -``` - -输出示例： - -```bash -{ - "result": "success" -} -``` - -#### **知识库文档列表** - -输入示例： - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents' \ ---header 'Authorization: Bearer {api_key}' -``` - -输出示例： - -```json -{ - "data": [ - { - "id": "", - "position": 1, - "data_source_type": "file_upload", - "data_source_info": null, - "dataset_process_rule_id": null, - "name": "dify", - "created_from": "", - "created_by": "", - "created_at": 1681623639, - "tokens": 0, - "indexing_status": "waiting", - "error": null, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "archived": false - }, - ], - "has_more": false, - "limit": 20, - "total": 9, - "page": 1 -} -``` - -#### **新增分段** - -输入示例： - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"segments": [{"content": "1","answer": "1","keywords": ["a"]}]}' -``` - -输出示例： - -```json -{ - "data": [{ - "id": "", - "position": 1, - "document_id": "", - "content": "1", - "answer": "1", - "word_count": 25, - "tokens": 0, - "keywords": [ - "a" - ], - "index_node_id": "", - "index_node_hash": "", - "hit_count": 0, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "status": "completed", - "created_by": "", - "created_at": 1695312007, - "indexing_at": 1695312007, - "completed_at": 1695312007, - "error": null, - "stopped_at": null - }], - "doc_form": "text_model" -} - -``` - -### 查询文档分段 - -输入示例： - -```bash -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' -``` - -输出示例： - -```bash -{ - "data": [{ - "id": "", - "position": 1, - "document_id": "", - "content": "1", - "answer": "1", - "word_count": 25, - "tokens": 0, - "keywords": [ - "a" - ], - "index_node_id": "", - "index_node_hash": "", - "hit_count": 0, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "status": "completed", - "created_by": "", - "created_at": 1695312007, - "indexing_at": 1695312007, - "completed_at": 1695312007, - "error": null, - "stopped_at": null - }], - "doc_form": "text_model" -} -``` - -### 删除文档分段 - -输入示例： - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' -``` - -输出示例： - -```bash -{ - "result": "success" -} -``` - -### 更新文档分段 - -输入示例： - -```bash -curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json'\ ---data-raw '{"segment": {"content": "1","answer": "1", "keywords": ["a"], "enabled": false}}' -``` - -输出示例： - -```bash -{ - "data": [{ - "id": "", - "position": 1, - "document_id": "", - "content": "1", - "answer": "1", - "word_count": 25, - "tokens": 0, - "keywords": [ - "a" - ], - "index_node_id": "", - "index_node_hash": "", - "hit_count": 0, - "enabled": true, - "disabled_at": null, - "disabled_by": null, - "status": "completed", - "created_by": "", - "created_at": 1695312007, - "indexing_at": 1695312007, - "completed_at": 1695312007, - "error": null, - "stopped_at": null - }], - "doc_form": "text_model" -} -``` - -#### 新增知识库元数据字段 - -输入示例： - -```bash -curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer {api_key}' \ ---data '{ - "type":"string", - "name":"test" -}' -``` - -输出示例： - -```json -{ - "id": "9f63c91b-d60e-4142-bb0c-c81a54dc2db5", - "type": "string", - "name": "test" -} -``` - -#### 更新知识库元数据字段 - -输入示例： - -```bash -curl --location --request PATCH 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/{metadata_id}' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json'\ ---data-raw '{"name": "test"}' -``` - -输出示例： - -```json -{ - "id": "abc", - "type": "string", - "name": "test", -} -``` - -#### 删除知识库元数据字段 - -输入示例： - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/{metadata_id}' \ ---header 'Authorization: Bearer {api_key}' -``` - -输出示例： - -```bash -200 success -``` - -#### 启用/禁用知识库元数据中的内置字段 - -输入示例： - -```bash -curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata/built-in/{action}' \ ---header 'Authorization: Bearer {api_key}' -``` - -输出示例： - -```json -200 success -``` - -#### 修改文档的元数据（赋值） - -输入示例： - -```bash -curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/metadata' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer {api_key}' ---data '{ - "operation_data":[ - { - "document_id": "3e928bc4-65ea-4201-87c8-cbcc5871f525", - "metadata_list": [ - { - "id": "1887f5ec-966f-4c93-8c99-5ad386022f46", - "value": "dify", - "name": "test" - } - ] - } - ] -}' -``` - -输出示例： - -```json -200 success -``` - -#### 数据集的元数据列表 - -输入示例： - -```bash -curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata' \ ---header 'Authorization: Bearer {api_key}' -``` - -输出示例： - -```json -{ - "doc_metadata": [ - { - "id": "550e8400-e29b-41d4-a716-446655440000", - "type": "string", - "name": "title", - "use_count": 42 - }, - { - "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", - "type": "number", - "name": "price", - "use_count": 28 - }, - { - "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c9", - "type": "time", - "name": "created_at", - "use_count": 35 - } - ], - "built_in_field_enabled": true -} -``` - -### 错误信息 - -| 错误信息 | 错误码 | 原因描述 | -|------|--------|---------| -| no_file_uploaded | 400 | 请上传你的文件 | -| too_many_files | 400 | 只允许上传一个文件 | -| file_too_large | 413 | 文件大小超出限制 | -| unsupported_file_type | 415 | 不支持的文件类型。目前只支持以下内容格式：`txt`, `markdown`, `md`, `pdf`, `html`, `html`, `xlsx`, `docx`, `csv` | -| high_quality_dataset_only | 400 | 当前操作仅支持"高质量"知识库 | -| dataset_not_initialized | 400 | 知识库仍在初始化或索引中。请稍候 | -| archived_document_immutable | 403 | 归档文档不可编辑 | -| dataset_name_duplicate | 409 | 知识库名称已存在，请修改你的知识库名称 | -| invalid_action | 400 | 无效操作 | -| document_already_finished | 400 | 文档已处理完成。请刷新页面或查看文档详情 | -| document_indexing | 400 | 文档正在处理中，无法编辑 | -| invalid_metadata | 400 | 元数据内容不正确。请检查并验证 | +有关完整的端点列表、请求/响应结构、错误码和交互式示例，请参阅[知识库 API 参考](https://docs.dify.ai/api-reference/知识库/获取知识库列表)。