diff --git a/en/SUMMARY.md b/en/SUMMARY.md index 38a1a4972..dcb370501 100644 --- a/en/SUMMARY.md +++ b/en/SUMMARY.md @@ -103,6 +103,7 @@ * [Annotation](guides/annotation/README.md) * [Logs and Annotation](guides/annotation/logs.md) * [Annotation Reply](guides/annotation/annotation-reply.md) + * [Maintain Annotation via API](guides/annotation/maintain-annotation-via-api.md) * [Monitoring](guides/monitoring/README.md) * [Data Analysis](guides/monitoring/analysis.md) * [Integrate External Ops Tools](guides/monitoring/integrate-external-ops-tools/README.md) diff --git a/en/guides/annotation/maintain-annotation-via-api.md b/en/guides/annotation/maintain-annotation-via-api.md new file mode 100644 index 000000000..c80805563 --- /dev/null +++ b/en/guides/annotation/maintain-annotation-via-api.md @@ -0,0 +1,147 @@ +# Maintain Annotations via API + +> Authentication and invocation methods are consistent with the App Service API. + +Maintaining annotations via API allows for operations such as adding, deleting, updating, and querying annotations. This provides more comprehensive third-party system integration capabilities. + +## How to Use + +Enter the workspace, go to the application, and click on Access API on the left side. Click on API Key in the upper right corner, then click Create Key. This will give you a key specific to this application. The API interface will recognize the application based on this key. + +## API Call Examples + +### Get Annotation List + +```bash +curl --location --request GET 'https://api.dify.ai/v1/apps/annotations?page=1&limit=20' \ +--header 'Authorization: Bearer {api_key}' +``` + +Output Example: + +```json +{ + "data": [ + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 +} +``` + +### Create Annotation + +```bash +curl --location --request POST 'https://api.dify.ai/v1/apps/annotations' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "question": "What is your name?", + "answer": "I am Dify." +}' +``` + +Output Example: + +```json +{ + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 +} +``` + +### Update Annotation + +```bash +curl --location --request PUT 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "question": "What is your name?", + "answer": "I am Dify." +}' +``` + +Output Example: + +```json +{ + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 +} +``` + +### Delete Annotation + +```bash +curl --location --request DELETE 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \ +--header 'Authorization: Bearer {api_key}' +``` + +Output Example: + +```json +{"result": "success"} +``` + +### Initial Annotation Reply Settings + +```bash +curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/{action}' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "score_threshold": 0.9, + "embedding_provider_name": "zhipu", + "embedding_model_name": "embedding_3" +}' +``` + +Parameter Description: +- `action`: Can only be `enable` or `disable` +- `embedding_model_provider`: Specified embedding model provider, must be set up in the system first, corresponding to the provider field +- `embedding_model`: Specified embedding model, corresponding to the model field +- `score_threshold`: The similarity threshold for matching annotated replies. Only annotations with scores above this threshold will be recalled. + +The provider and model name of the embedding model can be obtained through the following interface: `v1/workspaces/current/models/model-types/text-embedding`. For specific instructions, see: [Maintain Knowledge Base via API](guides/knowledge-base/maintain-dataset-via-api.md). The Authorization used is the Dataset API Token. + +Output Example: + +```json +{ + "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", + "job_status": "waiting" +} +``` +This interface is executed asynchronously, so it will return a job_id. You can get the final execution result by querying the job status interface. + +### Query Initial Annotation Reply Settings Task Status + +```bash +curl --location --request GET 'https://api.dify.ai/v1/apps/annotation-reply/{action}/status/{job_id}' \ +--header 'Authorization: Bearer {api_key}' +``` + +Output Example: + +```json +{ + "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", + "job_status": "waiting", + "error_msg": "" +} +``` \ No newline at end of file diff --git a/en/guides/knowledge-base/maintain-dataset-via-api.md b/en/guides/knowledge-base/maintain-dataset-via-api.md index f79fcb07d..15f657159 100644 --- a/en/guides/knowledge-base/maintain-dataset-via-api.md +++ b/en/guides/knowledge-base/maintain-dataset-via-api.md @@ -27,7 +27,7 @@ This api is based on an existing Knowledge and creates a new document through te Request example: -```json +```bash 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' \ @@ -77,7 +77,7 @@ curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/doc --data-raw '{"name": "text","text": "text","indexing_technique": "high_quality","process_rule": {"mode": "automatic"}}' ``` -```bash +```json { "document": { "id": "", @@ -113,7 +113,7 @@ This api is based on an existing Knowledge and creates a new document through a Request example: -```json +```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' \ @@ -207,41 +207,203 @@ Response example: { "data": [ { - "id": "", - "name": "name", - "description": "desc", + "id": "eaedb485-95ac-4ffd-ab1e-18da6d676a2f", + "name": "Test Knowledge Base", + "description": "", + "provider": "vendor", "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": "" - }, - ... + "data_source_type": null, + "indexing_technique": null, + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "created_at": 1735620612, + "updated_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "updated_at": 1735620612, + "embedding_model": null, + "embedding_model_provider": null, + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 2, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": null, + "external_knowledge_info": { + "external_knowledge_id": null, + "external_knowledge_api_id": null, + "external_knowledge_api_name": null, + "external_knowledge_api_endpoint": null + }, + "external_retrieval_model": { + "top_k": 2, + "score_threshold": 0.0, + "score_threshold_enabled": null + } + } ], - "has_more": true, + "has_more": false, "limit": 20, - "total": 50, + "total": 1, "page": 1 } ``` +### **View Knowledge Base** +Get knowledge base details by knowledge base ID + +```bash +curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}' \ +--header 'Authorization: Bearer {api_key}' +``` + +Response example: + +输出示例： + +```json +{ + "id": "eaedb485-95ac-4ffd-ab1e-18da6d676a2f", + "name": "Test Knowledge Base", + "description": "", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": null, + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "created_at": 1735620612, + "updated_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "updated_at": 1735620612, + "embedding_model": null, + "embedding_model_provider": null, + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 2, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": null, + "external_knowledge_info": { + "external_knowledge_id": null, + "external_knowledge_api_id": null, + "external_knowledge_api_name": null, + "external_knowledge_api_endpoint": null + }, + "external_retrieval_model": { + "top_k": 2, + "score_threshold": 0.0, + "score_threshold_enabled": null + } +} +``` + +### **Update Knowledge Base** +Update a knowledge base by knowledge base ID + +```bash +curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' \ +--data-raw '{"name": "Test Knowledge Base", "indexing_technique": "high_quality", "permission": "only_me",\ + "embedding_model_provider": "zhipuai", "embedding_model": "embedding-3", "retrieval_model": "", "partial_member_list": []}' +``` + +Parameters: +- indexing_technique: high_quality, economy, None +- permission: only_me, all_team_members, partial_members (this partial_members option specifies team members) +- embedding_model_provider: specified embedding model provider, must be set up in the system first, corresponding to the provider field +- embedding_model: specified embedding model, corresponding to the model field +- retrieval_model: specified retrieval model, corresponding to the model field + +The provider and model name of the embedding model can be obtained through the following interface: +v1/workspaces/current/models/model-types/text-embedding. For specific instructions, see the following text. +The Authorization used is the Dataset API Token. + +Response example: + +```json +{ + "id": "eaedb485-95ac-4ffd-ab1e-18da6d676a2f", + "name": "Test Knowledge Base", + "description": "", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "created_at": 1735620612, + "updated_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "updated_at": 1735622679, + "embedding_model": "embedding-3", + "embedding_model_provider": "zhipuai", + "embedding_available": null, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 2, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": null, + "external_knowledge_info": { + "external_knowledge_id": null, + "external_knowledge_api_id": null, + "external_knowledge_api_name": null, + "external_knowledge_api_endpoint": null + }, + "external_retrieval_model": { + "top_k": 2, + "score_threshold": 0.0, + "score_threshold_enabled": null + }, + "partial_member_list": [] +} +``` + ### Delete a knowledge base Request example: -```json +```bash curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}' \ --header 'Authorization: Bearer {api_key}' ``` Response example: -```json +``` 204 No Content ``` @@ -413,7 +575,7 @@ Response example: "disabled_at": null, "disabled_by": null, "archived": false - }, + } ], "has_more": false, "limit": 20, @@ -654,6 +816,89 @@ Response example: } ``` +### Get available embedding models + +```bash +curl --location --request GET 'http://localhost:5001/v1/workspaces/current/models/model-types/text-embedding' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' +``` + +Response example: + +```json +{ + "data": [ + { + "provider": "zhipuai", + "label": { + "zh_Hans": "智谱 AI", + "en_US": "ZHIPU AI" + }, + "icon_small": { + "zh_Hans": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_small/zh_Hans", + "en_US": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_small/en_US" + }, + "icon_large": { + "zh_Hans": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_large/zh_Hans", + "en_US": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_large/en_US" + }, + "status": "active", + "models": [ + { + "model": "embedding-3", + "label": { + "zh_Hans": "embedding-3", + "en_US": "embedding-3" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 8192 + }, + "deprecated": false, + "status": "active", + "load_balancing_enabled": false + }, + { + "model": "embedding-2", + "label": { + "zh_Hans": "embedding-2", + "en_US": "embedding-2" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 8192 + }, + "deprecated": false, + "status": "active", + "load_balancing_enabled": false + }, + { + "model": "text_embedding", + "label": { + "zh_Hans": "text_embedding", + "en_US": "text_embedding" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 512 + }, + "deprecated": false, + "status": "active", + "load_balancing_enabled": false + } + ] + } + ] +} +``` + ### Error message Response example: diff --git a/zh_CN/SUMMARY.md b/zh_CN/SUMMARY.md index fbc9fc50f..b0e67c11e 100644 --- a/zh_CN/SUMMARY.md +++ b/zh_CN/SUMMARY.md @@ -103,6 +103,7 @@ * [标注](guides/annotation/README.md) * [日志与标注](guides/annotation/logs.md) * [标注回复](guides/annotation/annotation-reply.md) + * [通过 API 维护标注](guides/annotation/maintain-annotation-via-api.md) * [监测](guides/monitoring/README.md) * [集成外部 Ops 工具](guides/monitoring/integrate-external-ops-tools/README.md) * [集成 LangSmith](guides/monitoring/integrate-external-ops-tools/integrate-langsmith.md) diff --git a/zh_CN/features/datasets/maintain-dataset-via-api.md b/zh_CN/features/datasets/maintain-dataset-via-api.md deleted file mode 100644 index fbd49b55e..000000000 --- a/zh_CN/features/datasets/maintain-dataset-via-api.md +++ /dev/null @@ -1,145 +0,0 @@ -# 维护 Knowledge API - -> 身份验证、调用方法和应用服务API保持一致。区别在于知识API令牌可以对所有知识库进行操作. - -### 使用 Knowledge API 的好处 -* 同步你的数据系统以分散Knowledge以创建强大的工作流. -* 提供知识列表和文档列表API以及详细查询接口, 目的是为了便于生成自己的数据管理页. -* 为了简化你的同步进程，支持纯文本和 文件上传 / 更新文档 以及批量新增和修改. -* 提高Dify软件和服务的可见性，缩短手动处理文档和同步的时间. - -### 如何使用 - -请转到知识页面，你可以在左侧导航中切换到API页面。在此页面上，你可以查看dify提供的API文档并管理用于访问Knowledge API的凭据. - -

Knowledge API Document

- -## **创建空的 Knowledge** - -**`POST /datasets`** - -{% hint style="warning" %} -仅用于创建空知识库 -{% endhint %} - -``` -curl --location --request POST 'https://api.dify.ai/v1/datasets' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data-raw '{"name": "name"}' - -``` - -#### **Knowledge 列表** - - -``` -curl --location --request GET 'https://api.dify.ai/v1/datasets?page=1&limit=20' \ ---header 'Authorization: Bearer {api_key}' - -``` - -#### **文本创建文档** - -``` -curl --location --request POST '/document/create_by_text>' \\ ---header 'Authorization: Bearer {api_key}' \\ ---header 'Content-Type: application/json' \\ ---data-raw '{ - "name": "Dify", - "text": "Dify means Do it for you...", - "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" - } -}' - -``` - -#### **文件创建文档** - -``` -curl --location POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create_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"' - -``` - -#### **获取文档嵌入状态** - -``` -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{batch}/indexing-status' \ ---header 'Authorization: Bearer {api_key}' -``` - -#### **删除文档** - -``` -curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/documents' \ ---header 'Authorization: Bearer {api_key}' - -``` - -#### **添加新的片段** - -``` -curl --location 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments' \ ---header 'Authorization: Bearer {api_key}' \ ---header 'Content-Type: application/json' \ ---data '{"segments": [{"content": "1","answer": "1","keywords": ["a"]}]}' -``` - -#### 删除文档分段 - -``` -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' -``` - -### 报错信息 - -- `document_indexing`，表示文档正处于索引过程中 -- `provider_not_initialize`， 表示未配置嵌入模型 -- `not_found`，文档不存在 -- `dataset_name_duplicate` ，重复命名 -- `provider_quota_exceeded`，配额已超出最大限制 -- `dataset_not_initialized`，未进行初始化 -- `unsupported_file_type`，不支持的文件类型 - - 现支持的文件类型如下：txt, markdown, md, pdf, html, htm, xlsx, docx, csv -- `too_many_files`，表示文件数量太大，暂时只支持单文件上传 -- `file_too_large`，表示文件太大，仅支持15M以下的文件 \ No newline at end of file diff --git a/zh_CN/features/datasets/sync-from-notion.md b/zh_CN/features/datasets/sync-from-notion.md deleted file mode 100644 index 1dcd31774..000000000 --- a/zh_CN/features/datasets/sync-from-notion.md +++ /dev/null @@ -1,74 +0,0 @@ -# 概念同步 - -Dify的概念支持从概念导入并设置 **同步** 以便在概念更新后自动同步数据以进行更新. - -### 鉴权 - -1. 当创建知识库时, 选择数据源, 点击 **从概念同步--转到连接**, 并根据提示完成授权验证. -2. 你也可以: 点击 **设置--数据源--添加数据源**, 点击概念来源 **连接** 以完成鉴权. - -

概念链接

- -### 导入数据 - -完成鉴权操作后, 前往构建知识库页面, 点击 **概念同步**, 选择要导入的所需授权页面. - -### 分段清洗 - -接下来, 选择你的 **分段设置** 和 **索引方法**, **保存并处理**. 等待dify数据处理, 通常此步骤需要在LLM提供程序中使用令牌. 不仅支持导入普通页面类型，还可以汇总保存数据库类型下的页面属性. - -_**便笺:当前不支持导入图像和文件。表数据将转换为文本.**_ - -### 同步概念数据 - -如果你的概念内容已被修改，你可以直接在dify知识文档列表页面上单击[同步]按钮，一键同步数据(请注意，每次单击都会同步当前内容)。此步骤需要使用令牌. - -

同步概念数据

- -### (社区版) 概念集成配置指南 - -集成分为两种方式: **内部集成** 和 **公共集成** . 它可以按需在dify中配置. - -有关这两种集成方法的具体区别，请参阅 [概念正式说明](https://developers.notion.com/docs/authorization). - -#### 1. **使用内部集成** - -创建你的集成页面 [集成设置](https://www.notion.so/my-integrations) . 默认状态下, 所有集成都从内部集成开始; 内部集成将与你选择的工作空间相关联, 因此，你需要是工作区所有者才能创建集成. - -**具体操作步骤:** - -点击 " **New integration** " 按钮, 即默认为内部(不能修改), 选择关联的空间, 输入名称并上传logo, 点击"**提交**" 成功创建集成. - -
- -一旦创建了集成, 你可以根据需要更新其设置。 **性能** 此选项卡，然后再单击 "**显示**" 按钮后 **密钥** 复制你的密钥. - -
- -将其复制并返回到dify源代码 , 在 **.env** 文件与配置相关的环境变量中，环境变量如下: - -**NOTION\_INTEGRATION\_TYPE** = 内部 或 **NOTION\_INTEGRATION\_TYPE** = 公用 - -**NOTION\_INTERNAL\_SECRET**= 你的内部密钥 - -#### 2. **使用公共集成** - -**你需要将内部集成升级为公共集成** , 导航到集成分发页面，并切换开关以显示集成. - -要将开关切换到公共设置，你需要 **在组织信息中填写其他信息**, 包括你的公司名称, 网址, 和重定向目标路径, 然后点击 "提交" 按钮. - -
- -在你公共集成成功后， 在你的[集成设置页面](https://www.notion.so/my-integrations), 你将能够在[密钥]选项卡中访问集成的密钥. - -
- -返回到dify源代码,在 **.env** 与文件配置相关的环境变量中, 环境变量如下: - -**NOTION\_INTEGRATION\_TYPE**=公共 - -**NOTION\_CLIENT\_SECRET**=你的客户端密钥 - -**NOTION\_CLIENT\_ID**=你的客户端id - -配置完成后，你将能够使用知识部分中的概念数据导入和同步功能. diff --git a/zh_CN/guides/annotation/maintain-annotation-via-api.md b/zh_CN/guides/annotation/maintain-annotation-via-api.md new file mode 100644 index 000000000..7102ea5a4 --- /dev/null +++ b/zh_CN/guides/annotation/maintain-annotation-via-api.md @@ -0,0 +1,149 @@ +# 通过 API 维护标注 + +> 鉴权、调用方式与App Service API 保持一致。 + +通过 API 维护标注，可以实现标注的增、删、改、查等操作。提供更加完整的第三方系统集成能力。 + +## 如何使用 + +进入工作室，进入应用，在左侧点击访问API。在右上角点击API密钥，然后点击创建密钥。即可获得这个应用专用的密钥。API接口会根据该密钥识别应用。 + +## API调用示例 + +### 获取标注列表 + +```bash +curl --location --request GET 'https://api.dify.ai/v1/apps/annotations?page=1&limit=20' \ +--header 'Authorization: Bearer {api_key}' +``` + +输出示例： + +```json +{ + "data": [ + { + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 + } + ], + "has_more": false, + "limit": 20, + "total": 1, + "page": 1 +} +``` + +### 创建标注 + +```bash +curl --location --request POST 'https://api.dify.ai/v1/apps/annotations' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "question": "What is your name?", + "answer": "I am Dify." +}' +``` + +输出示例： + +```json +{ + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 +} +``` + +### 更新标注 + +```bash +curl --location --request PUT 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "question": "What is your name?", + "answer": "I am Dify." +}' +``` + +输出示例： + +```json +{ + "id": "69d48372-ad81-4c75-9c46-2ce197b4d402", + "question": "What is your name?", + "answer": "I am Dify.", + "hit_count": 0, + "created_at": 1735625869 +} +``` + +### 删除标注 + +```bash +curl --location --request DELETE 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \ +--header 'Authorization: Bearer {api_key}' +``` + +输出示例： + +```json +{"result": "success"} +``` + +### 标注回复初始设置 + +```bash +curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/{action}' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "score_threshold": 0.9, + "embedding_provider_name": "zhipu", + "embedding_model_name": "embedding_3" +}' +``` + +入参说明： +- `action`： 只能是enable或者disable +- `embedding_model_provider`: 指定的嵌入模型提供商, 必须先在系统内设定好接入的模型，对应的是provider字段 +- `embedding_model`: 指定的嵌入模型，对应的是model字段 +- `score_threshold`: 相似度阈值，当相似度大于该阈值时，系统会自动回复，否则不回复 + +嵌入模型的提供商和模型名称可以通过以下接口获取：`v1/workspaces/current/models/model-types/text-embedding`， +具体见：[通过 API 维护知识库](guides/knowledge-base/maintain-dataset-via-api.md)。 +使用的Authorization是Dataset的API Token + +输出示例： + +```json +{ + "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", + "job_status": "waiting" +} +``` +该接口是异步执行，所以会返回一个job_id，通过查询job状态接口可以获取到最终的执行结果。 + +### 查询标注回复初始设置任务状态 + +```bash +curl --location --request GET 'https://api.dify.ai/v1/apps/annotation-reply/{action}/status/{job_id}' \ +--header 'Authorization: Bearer {api_key}' +``` + +输出示例： + +```json +{ + "job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802", + "job_status": "waiting", + "error_msg": "" +} +``` \ No newline at end of file diff --git a/zh_CN/guides/knowledge-base/maintain-dataset-via-api.md b/zh_CN/guides/knowledge-base/maintain-dataset-via-api.md index 225ea5c1a..78678ca0e 100644 --- a/zh_CN/guides/knowledge-base/maintain-dataset-via-api.md +++ b/zh_CN/guides/knowledge-base/maintain-dataset-via-api.md @@ -27,7 +27,7 @@ 输入示例： -```json +```bash 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' \ @@ -72,7 +72,7 @@ curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/doc 输入示例： -```json +```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' \ @@ -166,41 +166,201 @@ curl --location --request GET 'https://api.dify.ai/v1/datasets?page=1&limit=20' { "data": [ { - "id": "", - "name": "知识库名称", - "description": "描述信息", + "id": "eaedb485-95ac-4ffd-ab1e-18da6d676a2f", + "name": "Test Knowledge Base", + "description": "", + "provider": "vendor", "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": "" - }, - ... + "data_source_type": null, + "indexing_technique": null, + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "created_at": 1735620612, + "updated_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "updated_at": 1735620612, + "embedding_model": null, + "embedding_model_provider": null, + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 2, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": null, + "external_knowledge_info": { + "external_knowledge_id": null, + "external_knowledge_api_id": null, + "external_knowledge_api_name": null, + "external_knowledge_api_endpoint": null + }, + "external_retrieval_model": { + "top_k": 2, + "score_threshold": 0.0, + "score_threshold_enabled": null + } + } ], - "has_more": true, + "has_more": false, "limit": 20, - "total": 50, + "total": 1, "page": 1 } ``` +### **获取知识库详情** +通过知识库ID查看知识库详情 + +```bash +curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}' \ +--header 'Authorization: Bearer {api_key}' +``` + +输出示例： + +```json +{ + "id": "eaedb485-95ac-4ffd-ab1e-18da6d676a2f", + "name": "Test Knowledge Base", + "description": "", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": null, + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "created_at": 1735620612, + "updated_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "updated_at": 1735620612, + "embedding_model": null, + "embedding_model_provider": null, + "embedding_available": true, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 2, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": null, + "external_knowledge_info": { + "external_knowledge_id": null, + "external_knowledge_api_id": null, + "external_knowledge_api_name": null, + "external_knowledge_api_endpoint": null + }, + "external_retrieval_model": { + "top_k": 2, + "score_threshold": 0.0, + "score_threshold_enabled": null + } +} +``` + +### **修改知识库** +通过知识库ID修改知识库信息 + +```bash +curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' \ +--data-raw '{"name": "Test Knowledge Base", "indexing_technique": "high_quality", "permission": "only_me",\ + "embedding_model_provider": "zhipuai", "embedding_model": "embedding-3", "retrieval_model": "", "partial_member_list": []}' +``` + +入参选项： +- `indexing_technique`: high_quality, economy, None +- `permission`: only_me, all_team_members, partial_members (此partial_members选项是指定团队成员) +- `embedding_model_provider`: 指定的嵌入模型提供商, 必须先在系统内设定好接入的模型，对应的是provider字段 +- `embedding_model`: 指定的嵌入模型，对应的是model字段 +- `retrieval_model`: 指定的检索模型，对应的是model字段 + +嵌入模型的提供商和模型名称可以通过以下接口获取：`v1/workspaces/current/models/model-types/text-embedding`，具体说明见后文。 +使用的Authorization是Dataset的API Token + +输出示例 +： +```json +{ + "id": "eaedb485-95ac-4ffd-ab1e-18da6d676a2f", + "name": "Test Knowledge Base", + "description": "", + "provider": "vendor", + "permission": "only_me", + "data_source_type": null, + "indexing_technique": "high_quality", + "app_count": 0, + "document_count": 0, + "word_count": 0, + "created_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "created_at": 1735620612, + "updated_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6", + "updated_at": 1735622679, + "embedding_model": "embedding-3", + "embedding_model_provider": "zhipuai", + "embedding_available": null, + "retrieval_model_dict": { + "search_method": "semantic_search", + "reranking_enable": false, + "reranking_mode": null, + "reranking_model": { + "reranking_provider_name": "", + "reranking_model_name": "" + }, + "weights": null, + "top_k": 2, + "score_threshold_enabled": false, + "score_threshold": null + }, + "tags": [], + "doc_form": null, + "external_knowledge_info": { + "external_knowledge_id": null, + "external_knowledge_api_id": null, + "external_knowledge_api_name": null, + "external_knowledge_api_endpoint": null + }, + "external_retrieval_model": { + "top_k": 2, + "score_threshold": 0.0, + "score_threshold_enabled": null + }, + "partial_member_list": [] +} +``` + + ### 删除知识库 输入示例： -```json +```bash curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}' \ --header 'Authorization: Bearer {api_key}' ``` 输出示例： -```json +``` 204 No Content ``` @@ -328,7 +488,7 @@ curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/docu "disabled_at": null, "disabled_by": null, "archived": false - }, + } ], "has_more": false, "limit": 20, @@ -511,6 +671,8 @@ curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/retr }' ``` +输出示例： + ```bash { "query": { @@ -565,6 +727,89 @@ curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}/retr } ``` +### 获取嵌入模型列表 + +```bash +curl --location --request GET 'http://localhost:5001/v1/workspaces/current/models/model-types/text-embedding' \ +--header 'Authorization: Bearer {api_key}' \ +--header 'Content-Type: application/json' +``` + +输出示例： + +```json +{ + "data": [ + { + "provider": "zhipuai", + "label": { + "zh_Hans": "智谱 AI", + "en_US": "ZHIPU AI" + }, + "icon_small": { + "zh_Hans": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_small/zh_Hans", + "en_US": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_small/en_US" + }, + "icon_large": { + "zh_Hans": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_large/zh_Hans", + "en_US": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_large/en_US" + }, + "status": "active", + "models": [ + { + "model": "embedding-3", + "label": { + "zh_Hans": "embedding-3", + "en_US": "embedding-3" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 8192 + }, + "deprecated": false, + "status": "active", + "load_balancing_enabled": false + }, + { + "model": "embedding-2", + "label": { + "zh_Hans": "embedding-2", + "en_US": "embedding-2" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 8192 + }, + "deprecated": false, + "status": "active", + "load_balancing_enabled": false + }, + { + "model": "text_embedding", + "label": { + "zh_Hans": "text_embedding", + "en_US": "text_embedding" + }, + "model_type": "text-embedding", + "features": null, + "fetch_from": "predefined-model", + "model_properties": { + "context_size": 512 + }, + "deprecated": false, + "status": "active", + "load_balancing_enabled": false + } + ] + } + ] +} +``` + ### 错误信息