Skip to content

Commit a28c82b

Browse files
jasonfish568jasonfish568
committed
docs: Update Dataset API
- Remove redundant dataset docs at zh_CN/features/datasets/* - Add documentation for GET, PATCH endpoints of Dataset - Add documentation for get available models endpoint - Fix incorrect code type mark - Improve response example
1 parent 3f5c01e commit a28c82b

File tree

4 files changed

+533
-262
lines changed

4 files changed

+533
-262
lines changed

‎en/guides/knowledge-base/maintain-dataset-via-api.md

+267-22
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ This api is based on an existing Knowledge and creates a new document through te
2727

2828
Request example:
2929

30-
```json
30+
```bash
3131
curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create_by_text' \
3232
--header 'Authorization: Bearer {api_key}' \
3333
--header 'Content-Type: application/json' \
@@ -77,7 +77,7 @@ curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/doc
7777
--data-raw '{"name": "text","text": "text","indexing_technique": "high_quality","process_rule": {"mode": "automatic"}}'
7878
```
7979

80-
```bash
80+
```json
8181
{
8282
"document": {
8383
"id": "",
@@ -113,7 +113,7 @@ This api is based on an existing Knowledge and creates a new document through a
113113

114114
Request example:
115115

116-
```json
116+
```bash
117117
curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create_by_file' \
118118
--header 'Authorization: Bearer {api_key}' \
119119
--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:
207207
{
208208
"data": [
209209
{
210-
"id": "",
211-
"name": "name",
212-
"description": "desc",
210+
"id": "eaedb485-95ac-4ffd-ab1e-18da6d676a2f",
211+
"name": "Test Knowledge Base",
212+
"description": "",
213+
"provider": "vendor",
213214
"permission": "only_me",
214-
"data_source_type": "upload_file",
215-
"indexing_technique": "",
216-
"app_count": 2,
217-
"document_count": 10,
218-
"word_count": 1200,
219-
"created_by": "",
220-
"created_at": "",
221-
"updated_by": "",
222-
"updated_at": ""
223-
},
224-
...
215+
"data_source_type": null,
216+
"indexing_technique": null,
217+
"app_count": 0,
218+
"document_count": 0,
219+
"word_count": 0,
220+
"created_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6",
221+
"created_at": 1735620612,
222+
"updated_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6",
223+
"updated_at": 1735620612,
224+
"embedding_model": null,
225+
"embedding_model_provider": null,
226+
"embedding_available": true,
227+
"retrieval_model_dict": {
228+
"search_method": "semantic_search",
229+
"reranking_enable": false,
230+
"reranking_mode": null,
231+
"reranking_model": {
232+
"reranking_provider_name": "",
233+
"reranking_model_name": ""
234+
},
235+
"weights": null,
236+
"top_k": 2,
237+
"score_threshold_enabled": false,
238+
"score_threshold": null
239+
},
240+
"tags": [],
241+
"doc_form": null,
242+
"external_knowledge_info": {
243+
"external_knowledge_id": null,
244+
"external_knowledge_api_id": null,
245+
"external_knowledge_api_name": null,
246+
"external_knowledge_api_endpoint": null
247+
},
248+
"external_retrieval_model": {
249+
"top_k": 2,
250+
"score_threshold": 0.0,
251+
"score_threshold_enabled": null
252+
}
253+
}
225254
],
226-
"has_more": true,
255+
"has_more": false,
227256
"limit": 20,
228-
"total": 50,
257+
"total": 1,
229258
"page": 1
230259
}
231260
```
232261

262+
### **View Knowledge Base**
263+
Get knowledge base details by knowledge base ID
264+
265+
```bash
266+
curl --location --request GET 'https://api.dify.ai/v1/datasets/{dataset_id}' \
267+
--header 'Authorization: Bearer {api_key}'
268+
```
269+
270+
Response example:
271+
272+
输出示例：
273+
274+
```json
275+
{
276+
"id": "eaedb485-95ac-4ffd-ab1e-18da6d676a2f",
277+
"name": "Test Knowledge Base",
278+
"description": "",
279+
"provider": "vendor",
280+
"permission": "only_me",
281+
"data_source_type": null,
282+
"indexing_technique": null,
283+
"app_count": 0,
284+
"document_count": 0,
285+
"word_count": 0,
286+
"created_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6",
287+
"created_at": 1735620612,
288+
"updated_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6",
289+
"updated_at": 1735620612,
290+
"embedding_model": null,
291+
"embedding_model_provider": null,
292+
"embedding_available": true,
293+
"retrieval_model_dict": {
294+
"search_method": "semantic_search",
295+
"reranking_enable": false,
296+
"reranking_mode": null,
297+
"reranking_model": {
298+
"reranking_provider_name": "",
299+
"reranking_model_name": ""
300+
},
301+
"weights": null,
302+
"top_k": 2,
303+
"score_threshold_enabled": false,
304+
"score_threshold": null
305+
},
306+
"tags": [],
307+
"doc_form": null,
308+
"external_knowledge_info": {
309+
"external_knowledge_id": null,
310+
"external_knowledge_api_id": null,
311+
"external_knowledge_api_name": null,
312+
"external_knowledge_api_endpoint": null
313+
},
314+
"external_retrieval_model": {
315+
"top_k": 2,
316+
"score_threshold": 0.0,
317+
"score_threshold_enabled": null
318+
}
319+
}
320+
```
321+
322+
### **Update Knowledge Base**
323+
Update a knowledge base by knowledge base ID
324+
325+
```bash
326+
curl --location --request POST 'https://api.dify.ai/v1/datasets/{dataset_id}' \
327+
--header 'Authorization: Bearer {api_key}' \
328+
--header 'Content-Type: application/json' \
329+
--data-raw '{"name": "Test Knowledge Base", "indexing_technique": "high_quality", "permission": "only_me",'\
330+
"embedding_model_provider": "zhipuai", "embedding_model": "embedding-3", "retrieval_model": "", "partial_member_list": []}'
331+
```
332+
333+
Parameters:
334+
- indexing_technique: high_quality, economy, None
335+
- permission: only_me, all_team_members, partial_members (this partial_members option specifies team members)
336+
- embedding_model_provider: specified embedding model provider, must be set up in the system first, corresponding to the provider field
337+
- embedding_model: specified embedding model, corresponding to the model field
338+
- retrieval_model: specified retrieval model, corresponding to the model field
339+
340+
The provider and model name of the embedding model can be obtained through the following interface:
341+
v1/workspaces/current/models/model-types/text-embedding. For specific instructions, see the following text.
342+
The Authorization used is the Dataset API Token.
343+
344+
Response example:
345+
346+
```json
347+
{
348+
"id": "eaedb485-95ac-4ffd-ab1e-18da6d676a2f",
349+
"name": "Test Knowledge Base",
350+
"description": "",
351+
"provider": "vendor",
352+
"permission": "only_me",
353+
"data_source_type": null,
354+
"indexing_technique": "high_quality",
355+
"app_count": 0,
356+
"document_count": 0,
357+
"word_count": 0,
358+
"created_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6",
359+
"created_at": 1735620612,
360+
"updated_by": "e99a1635-f725-4951-a99a-1daaaa76cfc6",
361+
"updated_at": 1735622679,
362+
"embedding_model": "embedding-3",
363+
"embedding_model_provider": "zhipuai",
364+
"embedding_available": null,
365+
"retrieval_model_dict": {
366+
"search_method": "semantic_search",
367+
"reranking_enable": false,
368+
"reranking_mode": null,
369+
"reranking_model": {
370+
"reranking_provider_name": "",
371+
"reranking_model_name": ""
372+
},
373+
"weights": null,
374+
"top_k": 2,
375+
"score_threshold_enabled": false,
376+
"score_threshold": null
377+
},
378+
"tags": [],
379+
"doc_form": null,
380+
"external_knowledge_info": {
381+
"external_knowledge_id": null,
382+
"external_knowledge_api_id": null,
383+
"external_knowledge_api_name": null,
384+
"external_knowledge_api_endpoint": null
385+
},
386+
"external_retrieval_model": {
387+
"top_k": 2,
388+
"score_threshold": 0.0,
389+
"score_threshold_enabled": null
390+
},
391+
"partial_member_list": []
392+
}
393+
```
394+
233395
### Delete a knowledge base
234396
235397
Request example:
236398
237-
```json
399+
```bash
238400
curl --location --request DELETE 'https://api.dify.ai/v1/datasets/{dataset_id}' \
239401
--header 'Authorization: Bearer {api_key}'
240402
```
241403
242404
Response example:
243405
244-
```json
406+
```
245407
204 No Content
246408
```
247409
@@ -413,7 +575,7 @@ Response example:
413575
"disabled_at": null,
414576
"disabled_by": null,
415577
"archived": false
416-
},
578+
}
417579
],
418580
"has_more": false,
419581
"limit": 20,
@@ -654,6 +816,89 @@ Response example:
654816
}
655817
```
656818

819+
### Get available embedding models
820+
821+
```bash
822+
curl --location --request GET 'http://localhost:5001/v1/workspaces/current/models/model-types/text-embedding' \
823+
--header 'Authorization: Bearer {api_key}' \
824+
--header 'Content-Type: application/json'
825+
```
826+
827+
Response example:
828+
829+
```json
830+
{
831+
"data": [
832+
{
833+
"provider": "zhipuai",
834+
"label": {
835+
"zh_Hans": "智谱 AI",
836+
"en_US": "ZHIPU AI"
837+
},
838+
"icon_small": {
839+
"zh_Hans": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_small/zh_Hans",
840+
"en_US": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_small/en_US"
841+
},
842+
"icon_large": {
843+
"zh_Hans": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_large/zh_Hans",
844+
"en_US": "http://127.0.0.1:5001/console/api/workspaces/current/model-providers/zhipuai/icon_large/en_US"
845+
},
846+
"status": "active",
847+
"models": [
848+
{
849+
"model": "embedding-3",
850+
"label": {
851+
"zh_Hans": "embedding-3",
852+
"en_US": "embedding-3"
853+
},
854+
"model_type": "text-embedding",
855+
"features": null,
856+
"fetch_from": "predefined-model",
857+
"model_properties": {
858+
"context_size": 8192
859+
},
860+
"deprecated": false,
861+
"status": "active",
862+
"load_balancing_enabled": false
863+
},
864+
{
865+
"model": "embedding-2",
866+
"label": {
867+
"zh_Hans": "embedding-2",
868+
"en_US": "embedding-2"
869+
},
870+
"model_type": "text-embedding",
871+
"features": null,
872+
"fetch_from": "predefined-model",
873+
"model_properties": {
874+
"context_size": 8192
875+
},
876+
"deprecated": false,
877+
"status": "active",
878+
"load_balancing_enabled": false
879+
},
880+
{
881+
"model": "text_embedding",
882+
"label": {
883+
"zh_Hans": "text_embedding",
884+
"en_US": "text_embedding"
885+
},
886+
"model_type": "text-embedding",
887+
"features": null,
888+
"fetch_from": "predefined-model",
889+
"model_properties": {
890+
"context_size": 512
891+
},
892+
"deprecated": false,
893+
"status": "active",
894+
"load_balancing_enabled": false
895+
}
896+
]
897+
}
898+
]
899+
}
900+
```
901+
657902
### Error message
658903

659904
Response example:

0 commit comments

Comments
 (0)