Skip to content

Commit 85f8276

Browse files
jasonfish568jasonfish568
committed
docs: Add Annotation API documentation
Related to: PR#12237(langgenius/dify#12237)
1 parent a28c82b commit 85f8276

File tree

4 files changed

+298
-0
lines changed

4 files changed

+298
-0
lines changed

‎en/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@
103103
* [Annotation](guides/annotation/README.md)
104104
* [Logs and Annotation](guides/annotation/logs.md)
105105
* [Annotation Reply](guides/annotation/annotation-reply.md)
106+
* [Maintain Annotation via API](guides/annotation/maintain-annotation-via-api.md)
106107
* [Monitoring](guides/monitoring/README.md)
107108
* [Data Analysis](guides/monitoring/analysis.md)
108109
* [Integrate External Ops Tools](guides/monitoring/integrate-external-ops-tools/README.md)

‎en/guides/annotation/maintain-annotation-via-api.md

+147
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Maintain Annotations via API
2+
3+
> Authentication and invocation methods are consistent with the App Service API.
4+
5+
Maintaining annotations via API allows for operations such as adding, deleting, updating, and querying annotations. This provides more comprehensive third-party system integration capabilities.
6+
7+
## How to Use
8+
9+
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.
10+
11+
## API Call Examples
12+
13+
### Get Annotation List
14+
15+
```bash
16+
curl --location --request GET 'https://api.dify.ai/v1/apps/annotations?page=1&limit=20' \
17+
--header 'Authorization: Bearer {api_key}'
18+
```
19+
20+
Output Example:
21+
22+
```json
23+
{
24+
"data": [
25+
{
26+
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
27+
"question": "What is your name?",
28+
"answer": "I am Dify.",
29+
"hit_count": 0,
30+
"created_at": 1735625869
31+
}
32+
],
33+
"has_more": false,
34+
"limit": 20,
35+
"total": 1,
36+
"page": 1
37+
}
38+
```
39+
40+
### Create Annotation
41+
42+
```bash
43+
curl --location --request POST 'https://api.dify.ai/v1/apps/annotations' \
44+
--header 'Authorization: Bearer {api_key}' \
45+
--header 'Content-Type: application/json' \
46+
--data-raw '{
47+
"question": "What is your name?",
48+
"answer": "I am Dify."
49+
}'
50+
```
51+
52+
Output Example:
53+
54+
```json
55+
{
56+
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
57+
"question": "What is your name?",
58+
"answer": "I am Dify.",
59+
"hit_count": 0,
60+
"created_at": 1735625869
61+
}
62+
```
63+
64+
### Update Annotation
65+
66+
```bash
67+
curl --location --request PUT 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \
68+
--header 'Authorization: Bearer {api_key}' \
69+
--header 'Content-Type: application/json' \
70+
--data-raw '{
71+
"question": "What is your name?",
72+
"answer": "I am Dify."
73+
}'
74+
```
75+
76+
Output Example:
77+
78+
```json
79+
{
80+
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
81+
"question": "What is your name?",
82+
"answer": "I am Dify.",
83+
"hit_count": 0,
84+
"created_at": 1735625869
85+
}
86+
```
87+
88+
### Delete Annotation
89+
90+
```bash
91+
curl --location --request DELETE 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \
92+
--header 'Authorization: Bearer {api_key}'
93+
```
94+
95+
Output Example:
96+
97+
```json
98+
{"result": "success"}
99+
```
100+
101+
### Initial Annotation Reply Settings
102+
103+
```bash
104+
curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/{action}' \
105+
--header 'Authorization: Bearer {api_key}' \
106+
--header 'Content-Type: application/json' \
107+
--data-raw '{
108+
"score_threshold": 0.9,
109+
"embedding_provider_name": "zhipu",
110+
"embedding_model_name": "embedding_3"
111+
}'
112+
```
113+
114+
Parameter Description:
115+
- `action`: Can only be `enable` or `disable`
116+
- `embedding_model_provider`: Specified embedding model provider, must be set up in the system first, corresponding to the provider field
117+
- `embedding_model`: Specified embedding model, corresponding to the model field
118+
- `retrieval_model`: Specified retrieval model, corresponding to the model field
119+
120+
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.
121+
122+
Output Example:
123+
124+
```json
125+
{
126+
"job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
127+
"job_status": "waiting"
128+
}
129+
```
130+
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.
131+
132+
### Query Initial Annotation Reply Settings Task Status
133+
134+
```bash
135+
curl --location --request GET 'https://api.dify.ai/v1/apps/annotation-reply/{action}/status/{job_id}' \
136+
--header 'Authorization: Bearer {api_key}'
137+
```
138+
139+
Output Example:
140+
141+
```json
142+
{
143+
"job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
144+
"job_status": "waiting",
145+
"error_msg": ""
146+
}
147+
```

‎zh_CN/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@
103103
* [标注](guides/annotation/README.md)
104104
* [日志与标注](guides/annotation/logs.md)
105105
* [标注回复](guides/annotation/annotation-reply.md)
106+
* [通过 API 维护标注](guides/annotation/maintain-annotation-via-api.md)
106107
* [监测](guides/monitoring/README.md)
107108
* [集成外部 Ops 工具](guides/monitoring/integrate-external-ops-tools/README.md)
108109
* [集成 LangSmith](guides/monitoring/integrate-external-ops-tools/integrate-langsmith.md)

‎zh_CN/guides/annotation/maintain-annotation-via-api.md

+149
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# 通过 API 维护标注
2+
3+
> 鉴权、调用方式与App Service API 保持一致。
4+
5+
通过 API 维护标注，可以实现标注的增、删、改、查等操作。提供更加完整的第三方系统集成能力。
6+
7+
## 如何使用
8+
9+
进入工作室，进入应用，在左侧点击访问API。在右上角点击API密钥，然后点击创建密钥。即可获得这个应用专用的密钥。API接口会根据该密钥识别应用。
10+
11+
## API调用示例
12+
13+
### 获取标注列表
14+
15+
```bash
16+
curl --location --request GET 'https://api.dify.ai/v1/apps/annotations?page=1&limit=20' \
17+
--header 'Authorization: Bearer {api_key}'
18+
```
19+
20+
输出示例：
21+
22+
```json
23+
{
24+
"data": [
25+
{
26+
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
27+
"question": "What is your name?",
28+
"answer": "I am Dify.",
29+
"hit_count": 0,
30+
"created_at": 1735625869
31+
}
32+
],
33+
"has_more": false,
34+
"limit": 20,
35+
"total": 1,
36+
"page": 1
37+
}
38+
```
39+
40+
### 创建标注
41+
42+
```bash
43+
curl --location --request POST 'https://api.dify.ai/v1/apps/annotations' \
44+
--header 'Authorization: Bearer {api_key}' \
45+
--header 'Content-Type: application/json' \
46+
--data-raw '{
47+
"question": "What is your name?",
48+
"answer": "I am Dify."
49+
}'
50+
```
51+
52+
输出示例：
53+
54+
```json
55+
{
56+
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
57+
"question": "What is your name?",
58+
"answer": "I am Dify.",
59+
"hit_count": 0,
60+
"created_at": 1735625869
61+
}
62+
```
63+
64+
### 更新标注
65+
66+
```bash
67+
curl --location --request PUT 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \
68+
--header 'Authorization: Bearer {api_key}' \
69+
--header 'Content-Type: application/json' \
70+
--data-raw '{
71+
"question": "What is your name?",
72+
"answer": "I am Dify."
73+
}'
74+
```
75+
76+
输出示例：
77+
78+
```json
79+
{
80+
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
81+
"question": "What is your name?",
82+
"answer": "I am Dify.",
83+
"hit_count": 0,
84+
"created_at": 1735625869
85+
}
86+
```
87+
88+
### 删除标注
89+
90+
```bash
91+
curl --location --request DELETE 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \
92+
--header 'Authorization: Bearer {api_key}'
93+
```
94+
95+
输出示例：
96+
97+
```json
98+
{"result": "success"}
99+
```
100+
101+
### 标注回复初始设置
102+
103+
```bash
104+
curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/{action}' \
105+
--header 'Authorization: Bearer {api_key}' \
106+
--header 'Content-Type: application/json' \
107+
--data-raw '{
108+
"score_threshold": 0.9,
109+
"embedding_provider_name": "zhipu",
110+
"embedding_model_name": "embedding_3"
111+
}'
112+
```
113+
114+
入参说明：
115+
- `action`： 只能是enable或者disable
116+
- `embedding_model_provider`: 指定的嵌入模型提供商, 必须先在系统内设定好接入的模型，对应的是provider字段
117+
- `embedding_model`: 指定的嵌入模型，对应的是model字段
118+
- `retrieval_model`: 指定的检索模型，对应的是model字段
119+
120+
嵌入模型的提供商和模型名称可以通过以下接口获取：`v1/workspaces/current/models/model-types/text-embedding`，
121+
具体见：[通过 API 维护知识库](guides/knowledge-base/maintain-dataset-via-api.md)。
122+
使用的Authorization是Dataset的API Token
123+
124+
输出示例：
125+
126+
```json
127+
{
128+
"job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
129+
"job_status": "waiting"
130+
}
131+
```
132+
该接口是异步执行，所以会返回一个job_id，通过查询job状态接口可以获取到最终的执行结果。
133+
134+
### 查询标注回复初始设置任务状态
135+
136+
```bash
137+
curl --location --request GET 'https://api.dify.ai/v1/apps/annotation-reply/{action}/status/{job_id}' \
138+
--header 'Authorization: Bearer {api_key}'
139+
```
140+
141+
输出示例：
142+
143+
```json
144+
{
145+
"job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
146+
"job_status": "waiting",
147+
"error_msg": ""
148+
}
149+
```

0 commit comments

Comments
 (0)