mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-03-26 13:18:34 +07:00
Update the manage knowledge via api doc (#716)
* draft * add zh and ja translations
This commit is contained in:
Riskey
@@ -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.
|
||||
<Info>
|
||||
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.
|
||||
</Info>
|
||||
|
||||
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**.
|
||||
<Warning>
|
||||
Store your API key securely on the server side. Never expose it in client-side code or public repositories.
|
||||
</Warning>
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
<Warning>
|
||||
Only used to create an empty knowledge base.
|
||||
</Warning>
|
||||
|
||||
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.
|
||||
@@ -1,718 +1,33 @@
|
||||
---
|
||||
title: APIを活用したナレッジベースのメンテナンス
|
||||
title: APIによるナレッジベース管理
|
||||
description: Dify ナレッジベース API を使用してナレッジベースをプログラムで管理する
|
||||
---
|
||||
|
||||
<Note> ⚠️ このドキュメントはAIによって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api)を参照してください。</Note>
|
||||
Dify は、ナレッジベース、ドキュメント、チャンクをプログラムで管理するための完全なナレッジベース API セットを提供しています。データ同期の自動化や、ナレッジベース操作の CI/CD パイプラインへの統合に活用できます。
|
||||
|
||||
> 認証や呼び出し方法はサービスAPIと同様ですが、生成される各ナレッジベースAPIトークンには、現在のアカウントでアクセス可能なすべてのナレッジベースを操作する権限が付与されています。データの安全性には十分ご注意ください。
|
||||
ナレッジベースを作成すると、API アクセスはデフォルトで有効になります。API 呼び出しを開始するには、エンドポイントとキーの API 認証情報のみが必要です。
|
||||
|
||||
## ナレッジベースAPI活用のメリット
|
||||
<Info>
|
||||
1つのナレッジベース API キーで、同一アカウント配下の**すべてのアクセス可能なナレッジベース**を操作できます。意図しないデータ漏洩を防ぐため、認証情報は適切に管理してください。
|
||||
</Info>
|
||||
|
||||
APIによるナレッジベース管理はデータ処理効率を飛躍的に向上させます。コマンドラインからのデータ同期や自動化操作を容易に実現でき、UI操作の煩雑さから解放されます。
|
||||
## API エンドポイントとキーの取得
|
||||
|
||||
主なメリット：
|
||||
Dify で**ナレッジベース**ページに移動します。右上の **サービス API** をクリックして API 設定パネルを開きます。ここでは以下の操作が可能です：
|
||||
|
||||
* **自動同期**: データシステムとDifyナレッジベースをシームレスに連携し、効率的なワークフローを構築。
|
||||
* **総合管理**: ナレッジベースリスト、ドキュメントリスト、詳細検索機能を提供し、カスタム管理インターフェースの構築が可能。
|
||||
* **柔軟なアップロード**: テキスト直接入力とファイルアップロードを両方サポート、チャンク単位の一括操作に対応。
|
||||
* **生産性向上**: 手動作業時間を削減し、Difyプラットフォームの利用体験を最適化。
|
||||
- サービス API エンドポイントを取得します。これはすべてのナレッジベース API リクエストのベース URL です。
|
||||
- **API キー** をクリックして、新しいキーの作成や既存キーの管理を行います。
|
||||
|
||||
## 使用方法
|
||||
<Warning>
|
||||
API キーはサーバー側で安全に保管してください。クライアントサイドのコードや公開リポジトリには絶対に公開しないでください。
|
||||
</Warning>
|
||||
|
||||
ナレッジベース管理画面左側ナビゲーションの**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": ""
|
||||
}
|
||||
```
|
||||
|
||||
### 空白のナレッジベースを作成する
|
||||
|
||||
<Warning>
|
||||
空のデータセットを作成するためだけに使用
|
||||
</Warning>
|
||||
|
||||
入力例：
|
||||
|
||||
```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/データセット/ナレッジベースリストを取得)をご覧ください。
|
||||
|
||||
@@ -1,692 +1,33 @@
|
||||
---
|
||||
title: 通过 API 维护知识库
|
||||
description: 使用 Dify 知识库 API 以编程方式管理知识库
|
||||
---
|
||||
|
||||
<Note> ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考[英文原版](/en/use-dify/knowledge/manage-knowledge/maintain-dataset-via-api)。</Note>
|
||||
Dify 提供了一套完整的知识库 API，可以通过编程方式管理知识库、文档和分段。这对于自动化数据同步或将知识库操作集成到 CI/CD 流程中非常有用。
|
||||
|
||||
> 鉴权、调用方式与应用 Service API 保持一致，不同之处在于，所生成的单个知识库 API token 具备操作当前账号下所有可见知识库的权限，请注意数据安全。
|
||||
|
||||
### 使用知识库 API 的优势
|
||||
|
||||
通过 API 维护知识库可大幅提升数据处理效率，你可以通过命令行轻松同步数据，实现自动化操作，而无需在用户界面进行繁琐操作。
|
||||
|
||||
主要优势包括:
|
||||
|
||||
* 自动同步: 将数据系统与 Dify 知识库无缝对接，构建高效工作流程；
|
||||
* 全面管理: 提供知识库列表，文档列表及详情查询等功能，方便你自建数据管理界面；
|
||||
* 灵活上传: 支持纯文本和文件上传方式,可针对分段（Chunks）内容的批量新增和修改操作；
|
||||
* 提高效率: 减少手动处理时间，提升 Dify 平台使用体验。
|
||||
|
||||
### 如何使用
|
||||
|
||||
进入知识库页面，在左侧的导航中切换至 **API** 页面。在该页面中你可以查看 Dify 提供的知识库 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": ""
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
#### **创建空知识库**
|
||||
创建知识库时，API 访问默认开启。要开始调用 API，你只需要 API 凭据：一个端点和一个密钥。
|
||||
|
||||
<Info>
|
||||
仅用来创建空知识库
|
||||
单个知识库 API 密钥可以访问同一账号下的**所有可见知识库**。请妥善保管凭据，避免意外的数据泄露。
|
||||
</Info>
|
||||
|
||||
输入示例：
|
||||
## 获取 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
|
||||
}
|
||||
```
|
||||
<Warning>
|
||||
请将 API 密钥安全存储在服务端，切勿在客户端代码或公开仓库中暴露。
|
||||
</Warning>
|
||||
|
||||
#### **知识库列表**
|
||||
## 管理知识库的 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/知识库/获取知识库列表)。
|
||||
|
||||
Reference in New Issue
Block a user