template.zh.mdx 50 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452
  1. import { CodeGroup } from '@/app/components/develop/code.tsx'
  2. import { Row, Col, Properties, Property, Heading, SubProperty, PropertyInstruction, Paragraph } from '@/app/components/develop/md.tsx'
  3. # 知识库 API
  4. <div>
  5. ### 鉴权
  6. Dify Service API 使用 `API-Key` 进行鉴权。
  7. 建议开发者把 `API-Key` 放在后端存储,而非分享或者放在客户端存储,以免 `API-Key` 泄露,导致财产损失。
  8. 所有 API 请求都应在 **`Authorization`** HTTP Header 中包含您的 `API-Key`,如下所示:
  9. <CodeGroup title="Code">
  10. ```javascript
  11. Authorization: Bearer {API_KEY}
  12. ```
  13. </CodeGroup>
  14. </div>
  15. <hr className='ml-0 mr-0' />
  16. <Heading
  17. url='/datasets/{dataset_id}/document/create-by-text'
  18. method='POST'
  19. title='通过文本创建文档'
  20. name='#create-by-text'
  21. />
  22. <Row>
  23. <Col>
  24. 此接口基于已存在知识库,在此知识库的基础上通过文本创建新的文档
  25. ### Path
  26. <Properties>
  27. <Property name='dataset_id' type='string' key='dataset_id'>
  28. 知识库 ID
  29. </Property>
  30. </Properties>
  31. ### Request Body
  32. <Properties>
  33. <Property name='name' type='string' key='name'>
  34. 文档名称
  35. </Property>
  36. <Property name='text' type='string' key='text'>
  37. 文档内容
  38. </Property>
  39. <Property name='indexing_technique' type='string' key='indexing_technique'>
  40. 索引方式
  41. - <code>high_quality</code> 高质量:使用 embedding 模型进行嵌入,构建为向量数据库索引
  42. - <code>economy</code> 经济:使用 keyword table index 的倒排索引进行构建
  43. </Property>
  44. <Property name='doc_form' type='string' key='doc_form'>
  45. 索引内容的形式
  46. - <code>text_model</code> text 文档直接 embedding,经济模式默认为该模式
  47. - <code>hierarchical_model</code> parent-child 模式
  48. - <code>qa_model</code> Q&A 模式:为分片文档生成 Q&A 对,然后对问题进行 embedding
  49. </Property>
  50. <Property name='doc_language' type='string' key='doc_language'>
  51. 在 Q&A 模式下,指定文档的语言,例如:<code>English</code>、<code>Chinese</code>
  52. </Property>
  53. <Property name='process_rule' type='object' key='process_rule'>
  54. 处理规则
  55. - <code>mode</code> (string) 清洗、分段模式 ,automatic 自动 / custom 自定义
  56. - <code>rules</code> (object) 自定义规则(自动模式下,该字段为空)
  57. - <code>pre_processing_rules</code> (array[object]) 预处理规则
  58. - <code>id</code> (string) 预处理规则的唯一标识符
  59. - 枚举:
  60. - <code>remove_extra_spaces</code> 替换连续空格、换行符、制表符
  61. - <code>remove_urls_emails</code> 删除 URL、电子邮件地址
  62. - <code>enabled</code> (bool) 是否选中该规则,不传入文档 ID 时代表默认值
  63. - <code>segmentation</code> (object) 分段规则
  64. - <code>separator</code> 自定义分段标识符,目前仅允许设置一个分隔符。默认为 <code>\n</code>
  65. - <code>max_tokens</code> 最大长度(token)默认为 1000
  66. - <code>parent_mode</code> 父分段的召回模式 <code>full-doc</code> 全文召回 / <code>paragraph</code> 段落召回
  67. - <code>subchunk_segmentation</code> (object) 子分段规则
  68. - <code>separator</code> 分段标识符,目前仅允许设置一个分隔符。默认为 <code>***</code>
  69. - <code>max_tokens</code> 最大长度 (token) 需要校验小于父级的长度
  70. - <code>chunk_overlap</code> 分段重叠指的是在对数据进行分段时,段与段之间存在一定的重叠部分(选填)
  71. </Property>
  72. <PropertyInstruction>当知识库未设置任何参数的时候,首次上传需要提供以下参数,未提供则使用默认选项:</PropertyInstruction>
  73. <Property name='retrieval_model' type='object' key='retrieval_model'>
  74. 检索模式
  75. - <code>search_method</code> (string) 检索方法
  76. - <code>hybrid_search</code> 混合检索
  77. - <code>semantic_search</code> 语义检索
  78. - <code>full_text_search</code> 全文检索
  79. - <code>reranking_enable</code> (bool) 是否开启rerank
  80. - <code>reranking_model</code> (object) Rerank 模型配置
  81. - <code>reranking_provider_name</code> (string) Rerank 模型的提供商
  82. - <code>reranking_model_name</code> (string) Rerank 模型的名称
  83. - <code>top_k</code> (int) 召回条数
  84. - <code>score_threshold_enabled</code> (bool)是否开启召回分数限制
  85. - <code>score_threshold</code> (float) 召回分数限制
  86. </Property>
  87. <Property name='embedding_model' type='string' key='embedding_model'>
  88. Embedding 模型名称
  89. </Property>
  90. <Property name='embedding_model_provider' type='string' key='embedding_model_provider'>
  91. Embedding 模型供应商
  92. </Property>
  93. </Properties>
  94. </Col>
  95. <Col sticky>
  96. <CodeGroup
  97. title="Request"
  98. tag="POST"
  99. label="/datasets/{dataset_id}/document/create-by-text"
  100. targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/document/create-by-text' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"name": "text","text": "text","indexing_technique": "high_quality","process_rule": {"mode": "automatic"}}'`}
  101. >
  102. ```bash {{ title: 'cURL' }}
  103. curl --location --request --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/document/create-by-text' \
  104. --header 'Authorization: Bearer {api_key}' \
  105. --header 'Content-Type: application/json' \
  106. --data-raw '{
  107. "name": "text",
  108. "text": "text",
  109. "indexing_technique": "high_quality",
  110. "process_rule": {
  111. "mode": "automatic"
  112. }
  113. }'
  114. ```
  115. </CodeGroup>
  116. <CodeGroup title="Response">
  117. ```json {{ title: 'Response' }}
  118. {
  119. "document": {
  120. "id": "",
  121. "position": 1,
  122. "data_source_type": "upload_file",
  123. "data_source_info": {
  124. "upload_file_id": ""
  125. },
  126. "dataset_process_rule_id": "",
  127. "name": "text.txt",
  128. "created_from": "api",
  129. "created_by": "",
  130. "created_at": 1695690280,
  131. "tokens": 0,
  132. "indexing_status": "waiting",
  133. "error": null,
  134. "enabled": true,
  135. "disabled_at": null,
  136. "disabled_by": null,
  137. "archived": false,
  138. "display_status": "queuing",
  139. "word_count": 0,
  140. "hit_count": 0,
  141. "doc_form": "text_model"
  142. },
  143. "batch": ""
  144. }
  145. ```
  146. </CodeGroup>
  147. </Col>
  148. </Row>
  149. <hr className='ml-0 mr-0' />
  150. <Heading
  151. url='/datasets/{dataset_id}/document/create-by-file'
  152. method='POST'
  153. title='通过文件创建文档 '
  154. name='#create-by-file'
  155. />
  156. <Row>
  157. <Col>
  158. 此接口基于已存在知识库,在此知识库的基础上通过文件创建新的文档
  159. ### Path
  160. <Properties>
  161. <Property name='dataset_id' type='string' key='dataset_id'>
  162. 知识库 ID
  163. </Property>
  164. </Properties>
  165. ### Request Body
  166. <Properties>
  167. <Property name='data' type='multipart/form-data json string' key='data'>
  168. - <code>original_document_id</code> 源文档 ID(选填)
  169. - 用于重新上传文档或修改文档清洗、分段配置,缺失的信息从源文档复制
  170. - 源文档不可为归档的文档
  171. - 当传入 <code>original_document_id</code> 时,代表文档进行更新操作,<code>process_rule</code> 为可填项目,不填默认使用源文档的分段方式
  172. - 未传入 <code>original_document_id</code> 时,代表文档进行新增操作,<code>process_rule</code> 为必填
  173. - <code>indexing_technique</code> 索引方式
  174. - <code>high_quality</code> 高质量:使用 embedding 模型进行嵌入,构建为向量数据库索引
  175. - <code>economy</code> 经济:使用 keyword table index 的倒排索引进行构建
  176. - <code>doc_form</code> 索引内容的形式
  177. - <code>text_model</code> text 文档直接 embedding,经济模式默认为该模式
  178. - <code>hierarchical_model</code> parent-child 模式
  179. - <code>qa_model</code> Q&A 模式:为分片文档生成 Q&A 对,然后对问题进行 embedding
  180. - <code>doc_language</code> 在 Q&A 模式下,指定文档的语言,例如:<code>English</code>、<code>Chinese</code>
  181. - <code>process_rule</code> 处理规则
  182. - <code>mode</code> (string) 清洗、分段模式 ,automatic 自动 / custom 自定义
  183. - <code>rules</code> (object) 自定义规则(自动模式下,该字段为空)
  184. - <code>pre_processing_rules</code> (array[object]) 预处理规则
  185. - <code>id</code> (string) 预处理规则的唯一标识符
  186. - 枚举:
  187. - <code>remove_extra_spaces</code> 替换连续空格、换行符、制表符
  188. - <code>remove_urls_emails</code> 删除 URL、电子邮件地址
  189. - <code>enabled</code> (bool) 是否选中该规则,不传入文档 ID 时代表默认值
  190. - <code>segmentation</code> (object) 分段规则
  191. - <code>separator</code> 自定义分段标识符,目前仅允许设置一个分隔符。默认为 \n
  192. - <code>max_tokens</code> 最大长度(token)默认为 1000
  193. - <code>parent_mode</code> 父分段的召回模式 <code>full-doc</code> 全文召回 / <code>paragraph</code> 段落召回
  194. - <code>subchunk_segmentation</code> (object) 子分段规则
  195. - <code>separator</code> 分段标识符,目前仅允许设置一个分隔符。默认为 <code>***</code>
  196. - <code>max_tokens</code> 最大长度 (token) 需要校验小于父级的长度
  197. - <code>chunk_overlap</code> 分段重叠指的是在对数据进行分段时,段与段之间存在一定的重叠部分(选填)
  198. </Property>
  199. <Property name='file' type='multipart/form-data' key='file'>
  200. 需要上传的文件。
  201. </Property>
  202. <PropertyInstruction>当知识库未设置任何参数的时候,首次上传需要提供以下参数,未提供则使用默认选项:</PropertyInstruction>
  203. <Property name='retrieval_model' type='object' key='retrieval_model'>
  204. 检索模式
  205. - <code>search_method</code> (string) 检索方法
  206. - <code>hybrid_search</code> 混合检索
  207. - <code>semantic_search</code> 语义检索
  208. - <code>full_text_search</code> 全文检索
  209. - <code>reranking_enable</code> (bool) 是否开启rerank
  210. - <code>reranking_model</code> (object) Rerank 模型配置
  211. - <code>reranking_provider_name</code> (string) Rerank 模型的提供商
  212. - <code>reranking_model_name</code> (string) Rerank 模型的名称
  213. - <code>top_k</code> (int) 召回条数
  214. - <code>score_threshold_enabled</code> (bool)是否开启召回分数限制
  215. - <code>score_threshold</code> (float) 召回分数限制
  216. </Property>
  217. <Property name='embedding_model' type='string' key='embedding_model'>
  218. Embedding 模型名称
  219. </Property>
  220. <Property name='embedding_model_provider' type='string' key='embedding_model_provider'>
  221. Embedding 模型供应商
  222. </Property>
  223. </Properties>
  224. </Col>
  225. <Col sticky>
  226. <CodeGroup
  227. title="Request"
  228. tag="POST"
  229. label="/datasets/{dataset_id}/document/create-by-file"
  230. targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/document/create-by-file' \\\n--header 'Authorization: Bearer {api_key}' \\\n--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' \\\n--form 'file=@"/path/to/file"'`}
  231. >
  232. ```bash {{ title: 'cURL' }}
  233. curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/document/create-by-file' \
  234. --header 'Authorization: Bearer {api_key}' \
  235. --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' \
  236. --form 'file=@"/path/to/file"'
  237. ```
  238. </CodeGroup>
  239. <CodeGroup title="Response">
  240. ```json {{ title: 'Response' }}
  241. {
  242. "document": {
  243. "id": "",
  244. "position": 1,
  245. "data_source_type": "upload_file",
  246. "data_source_info": {
  247. "upload_file_id": ""
  248. },
  249. "dataset_process_rule_id": "",
  250. "name": "Dify.txt",
  251. "created_from": "api",
  252. "created_by": "",
  253. "created_at": 1695308667,
  254. "tokens": 0,
  255. "indexing_status": "waiting",
  256. "error": null,
  257. "enabled": true,
  258. "disabled_at": null,
  259. "disabled_by": null,
  260. "archived": false,
  261. "display_status": "queuing",
  262. "word_count": 0,
  263. "hit_count": 0,
  264. "doc_form": "text_model"
  265. },
  266. "batch": ""
  267. }
  268. ```
  269. </CodeGroup>
  270. </Col>
  271. </Row>
  272. <hr className='ml-0 mr-0' />
  273. <Heading
  274. url='/datasets'
  275. method='POST'
  276. title='创建空知识库'
  277. name='#create_empty_dataset'
  278. />
  279. <Row>
  280. <Col>
  281. ### Request Body
  282. <Properties>
  283. <Property name='name' type='string' key='name'>
  284. 知识库名称(必填)
  285. </Property>
  286. <Property name='description' type='string' key='description'>
  287. 知识库描述(选填)
  288. </Property>
  289. <Property name='indexing_technique' type='string' key='indexing_technique'>
  290. 索引模式(选填,建议填写)
  291. - <code>high_quality</code> 高质量
  292. - <code>economy</code> 经济
  293. </Property>
  294. <Property name='permission' type='string' key='permission'>
  295. 权限(选填,默认 only_me)
  296. - <code>only_me</code> 仅自己
  297. - <code>all_team_members</code> 所有团队成员
  298. - <code>partial_members</code> 部分团队成员
  299. </Property>
  300. <Property name='provider' type='string' key='provider'>
  301. Provider(选填,默认 vendor)
  302. - <code>vendor</code> 上传文件
  303. - <code>external</code> 外部知识库
  304. </Property>
  305. <Property name='external_knowledge_api_id' type='str' key='external_knowledge_api_id'>
  306. 外部知识库 API_ID(选填)
  307. </Property>
  308. <Property name='external_knowledge_id' type='str' key='external_knowledge_id'>
  309. 外部知识库 ID(选填)
  310. </Property>
  311. </Properties>
  312. </Col>
  313. <Col sticky>
  314. <CodeGroup
  315. title="Request"
  316. tag="POST"
  317. label="/datasets"
  318. targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"name": "name", "permission": "only_me"}'`}
  319. >
  320. ```bash {{ title: 'cURL' }}
  321. curl --location --request POST '${props.apiBaseUrl}/datasets' \
  322. --header 'Authorization: Bearer {api_key}' \
  323. --header 'Content-Type: application/json' \
  324. --data-raw '{
  325. "name": "name",
  326. "permission": "only_me"
  327. }'
  328. ```
  329. </CodeGroup>
  330. <CodeGroup title="Response">
  331. ```json {{ title: 'Response' }}
  332. {
  333. "id": "",
  334. "name": "name",
  335. "description": null,
  336. "provider": "vendor",
  337. "permission": "only_me",
  338. "data_source_type": null,
  339. "indexing_technique": null,
  340. "app_count": 0,
  341. "document_count": 0,
  342. "word_count": 0,
  343. "created_by": "",
  344. "created_at": 1695636173,
  345. "updated_by": "",
  346. "updated_at": 1695636173,
  347. "embedding_model": null,
  348. "embedding_model_provider": null,
  349. "embedding_available": null
  350. }
  351. ```
  352. </CodeGroup>
  353. </Col>
  354. </Row>
  355. <hr className='ml-0 mr-0' />
  356. <Heading
  357. url='/datasets'
  358. method='GET'
  359. title='知识库列表'
  360. name='#dataset_list'
  361. />
  362. <Row>
  363. <Col>
  364. ### Query
  365. <Properties>
  366. <Property name='page' type='string' key='page'>
  367. 页码
  368. </Property>
  369. <Property name='limit' type='string' key='limit'>
  370. 返回条数,默认 20,范围 1-100
  371. </Property>
  372. </Properties>
  373. </Col>
  374. <Col sticky>
  375. <CodeGroup
  376. title="Request"
  377. tag="GET"
  378. label="/datasets"
  379. targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets?page=1&limit=20' \\\n--header 'Authorization: Bearer {api_key}'`}
  380. >
  381. ```bash {{ title: 'cURL' }}
  382. curl --location --request GET '${props.apiBaseUrl}/datasets?page=1&limit=20' \
  383. --header 'Authorization: Bearer {api_key}'
  384. ```
  385. </CodeGroup>
  386. <CodeGroup title="Response">
  387. ```json {{ title: 'Response' }}
  388. {
  389. "data": [
  390. {
  391. "id": "",
  392. "name": "知识库名称",
  393. "description": "描述信息",
  394. "permission": "only_me",
  395. "data_source_type": "upload_file",
  396. "indexing_technique": "",
  397. "app_count": 2,
  398. "document_count": 10,
  399. "word_count": 1200,
  400. "created_by": "",
  401. "created_at": "",
  402. "updated_by": "",
  403. "updated_at": ""
  404. },
  405. ...
  406. ],
  407. "has_more": true,
  408. "limit": 20,
  409. "total": 50,
  410. "page": 1
  411. }
  412. ```
  413. </CodeGroup>
  414. </Col>
  415. </Row>
  416. <hr className='ml-0 mr-0' />
  417. <Heading
  418. url='/datasets/{dataset_id}'
  419. method='DELETE'
  420. title='删除知识库'
  421. name='#delete_dataset'
  422. />
  423. <Row>
  424. <Col>
  425. ### Path
  426. <Properties>
  427. <Property name='dataset_id' type='string' key='dataset_id'>
  428. 知识库 ID
  429. </Property>
  430. </Properties>
  431. </Col>
  432. <Col sticky>
  433. <CodeGroup
  434. title="Request"
  435. tag="DELETE"
  436. label="/datasets/{dataset_id}"
  437. targetCode={`curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}' \\\n--header 'Authorization: Bearer {api_key}'`}
  438. >
  439. ```bash {{ title: 'cURL' }}
  440. curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}' \
  441. --header 'Authorization: Bearer {api_key}'
  442. ```
  443. </CodeGroup>
  444. <CodeGroup title="Response">
  445. ```text {{ title: 'Response' }}
  446. 204 No Content
  447. ```
  448. </CodeGroup>
  449. </Col>
  450. </Row>
  451. <hr className='ml-0 mr-0' />
  452. <Heading
  453. url='/datasets/{dataset_id}/documents/{document_id}/update-by-text'
  454. method='POST'
  455. title='通过文本更新文档'
  456. name='#update-by-text'
  457. />
  458. <Row>
  459. <Col>
  460. 此接口基于已存在知识库,在此知识库的基础上通过文本更新文档
  461. ### Path
  462. <Properties>
  463. <Property name='dataset_id' type='string' key='dataset_id'>
  464. 知识库 ID
  465. </Property>
  466. <Property name='document_id' type='string' key='document_id'>
  467. 文档 ID
  468. </Property>
  469. </Properties>
  470. ### Request Body
  471. <Properties>
  472. <Property name='name' type='string' key='name'>
  473. 文档名称(选填)
  474. </Property>
  475. <Property name='text' type='string' key='text'>
  476. 文档内容(选填)
  477. </Property>
  478. <Property name='process_rule' type='object' key='process_rule'>
  479. 处理规则(选填)
  480. - <code>mode</code> (string) 清洗、分段模式 ,automatic 自动 / custom 自定义
  481. - <code>rules</code> (object) 自定义规则(自动模式下,该字段为空)
  482. - <code>pre_processing_rules</code> (array[object]) 预处理规则
  483. - <code>id</code> (string) 预处理规则的唯一标识符
  484. - 枚举:
  485. - <code>remove_extra_spaces</code> 替换连续空格、换行符、制表符
  486. - <code>remove_urls_emails</code> 删除 URL、电子邮件地址
  487. - <code>enabled</code> (bool) 是否选中该规则,不传入文档 ID 时代表默认值
  488. - <code>segmentation</code> (object) 分段规则
  489. - <code>separator</code> 自定义分段标识符,目前仅允许设置一个分隔符。默认为 \n
  490. - <code>max_tokens</code> 最大长度(token)默认为 1000
  491. - <code>parent_mode</code> 父分段的召回模式 <code>full-doc</code> 全文召回 / <code>paragraph</code> 段落召回
  492. - <code>subchunk_segmentation</code> (object) 子分段规则
  493. - <code>separator</code> 分段标识符,目前仅允许设置一个分隔符。默认为 <code>***</code>
  494. - <code>max_tokens</code> 最大长度 (token) 需要校验小于父级的长度
  495. - <code>chunk_overlap</code> 分段重叠指的是在对数据进行分段时,段与段之间存在一定的重叠部分(选填)
  496. </Property>
  497. </Properties>
  498. </Col>
  499. <Col sticky>
  500. <CodeGroup
  501. title="Request"
  502. tag="POST"
  503. label="/datasets/{dataset_id}/documents/{document_id}/update-by-text"
  504. targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/update-by-text' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"name": "name","text": "text"}'`}
  505. >
  506. ```bash {{ title: 'cURL' }}
  507. curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/update-by-text' \
  508. --header 'Authorization: Bearer {api_key}' \
  509. --header 'Content-Type: application/json' \
  510. --data-raw '{
  511. "name": "name",
  512. "text": "text"
  513. }'
  514. ```
  515. </CodeGroup>
  516. <CodeGroup title="Response">
  517. ```json {{ title: 'Response' }}
  518. {
  519. "document": {
  520. "id": "",
  521. "position": 1,
  522. "data_source_type": "upload_file",
  523. "data_source_info": {
  524. "upload_file_id": ""
  525. },
  526. "dataset_process_rule_id": "",
  527. "name": "name.txt",
  528. "created_from": "api",
  529. "created_by": "",
  530. "created_at": 1695308667,
  531. "tokens": 0,
  532. "indexing_status": "waiting",
  533. "error": null,
  534. "enabled": true,
  535. "disabled_at": null,
  536. "disabled_by": null,
  537. "archived": false,
  538. "display_status": "queuing",
  539. "word_count": 0,
  540. "hit_count": 0,
  541. "doc_form": "text_model"
  542. },
  543. "batch": ""
  544. }
  545. ```
  546. </CodeGroup>
  547. </Col>
  548. </Row>
  549. <hr className='ml-0 mr-0' />
  550. <Heading
  551. url='/datasets/{dataset_id}/documents/{document_id}/update-by-file'
  552. method='POST'
  553. title='通过文件更新文档'
  554. name='#update-by-file'
  555. />
  556. <Row>
  557. <Col>
  558. 此接口基于已存在知识库,在此知识库的基础上通过文件更新文档的操作。
  559. ### Path
  560. <Properties>
  561. <Property name='dataset_id' type='string' key='dataset_id'>
  562. 知识库 ID
  563. </Property>
  564. <Property name='document_id' type='string' key='document_id'>
  565. 文档 ID
  566. </Property>
  567. </Properties>
  568. ### Request Body
  569. <Properties>
  570. <Property name='name' type='string' key='name'>
  571. 文档名称(选填)
  572. </Property>
  573. <Property name='file' type='multipart/form-data' key='file'>
  574. 需要上传的文件
  575. </Property>
  576. <Property name='process_rule' type='object' key='process_rule'>
  577. 处理规则(选填)
  578. - <code>mode</code> (string) 清洗、分段模式 ,automatic 自动 / custom 自定义
  579. - <code>rules</code> (object) 自定义规则(自动模式下,该字段为空)
  580. - <code>pre_processing_rules</code> (array[object]) 预处理规则
  581. - <code>id</code> (string) 预处理规则的唯一标识符
  582. - 枚举:
  583. - <code>remove_extra_spaces</code> 替换连续空格、换行符、制表符
  584. - <code>remove_urls_emails</code> 删除 URL、电子邮件地址
  585. - <code>enabled</code> (bool) 是否选中该规则,不传入文档 ID 时代表默认值
  586. - <code>segmentation</code> (object) 分段规则
  587. - <code>separator</code> 自定义分段标识符,目前仅允许设置一个分隔符。默认为 \n
  588. - <code>max_tokens</code> 最大长度(token)默认为 1000
  589. - <code>parent_mode</code> 父分段的召回模式 <code>full-doc</code> 全文召回 / <code>paragraph</code> 段落召回
  590. - <code>subchunk_segmentation</code> (object) 子分段规则
  591. - <code>separator</code> 分段标识符,目前仅允许设置一个分隔符。默认为 <code>***</code>
  592. - <code>max_tokens</code> 最大长度 (token) 需要校验小于父级的长度
  593. - <code>chunk_overlap</code> 分段重叠指的是在对数据进行分段时,段与段之间存在一定的重叠部分(选填)
  594. </Property>
  595. </Properties>
  596. </Col>
  597. <Col sticky>
  598. <CodeGroup
  599. title="Request"
  600. tag="POST"
  601. label="/datasets/{dataset_id}/documents/{document_id}/update-by-file"
  602. targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/update-by-file' \\\n--header 'Authorization: Bearer {api_key}' \\\n--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' \\\n--form 'file=@"/path/to/file"'`}
  603. >
  604. ```bash {{ title: 'cURL' }}
  605. curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/update-by-file' \
  606. --header 'Authorization: Bearer {api_key}' \
  607. --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' \
  608. --form 'file=@"/path/to/file"'
  609. ```
  610. </CodeGroup>
  611. <CodeGroup title="Response">
  612. ```json {{ title: 'Response' }}
  613. {
  614. "document": {
  615. "id": "",
  616. "position": 1,
  617. "data_source_type": "upload_file",
  618. "data_source_info": {
  619. "upload_file_id": ""
  620. },
  621. "dataset_process_rule_id": "",
  622. "name": "Dify.txt",
  623. "created_from": "api",
  624. "created_by": "",
  625. "created_at": 1695308667,
  626. "tokens": 0,
  627. "indexing_status": "waiting",
  628. "error": null,
  629. "enabled": true,
  630. "disabled_at": null,
  631. "disabled_by": null,
  632. "archived": false,
  633. "display_status": "queuing",
  634. "word_count": 0,
  635. "hit_count": 0,
  636. "doc_form": "text_model"
  637. },
  638. "batch": "20230921150427533684"
  639. }
  640. ```
  641. </CodeGroup>
  642. </Col>
  643. </Row>
  644. <hr className='ml-0 mr-0' />
  645. <Heading
  646. url='/datasets/{dataset_id}/documents/{batch}/indexing-status'
  647. method='GET'
  648. title='获取文档嵌入状态(进度)'
  649. name='#indexing_status'
  650. />
  651. <Row>
  652. <Col>
  653. ### Path
  654. <Properties>
  655. <Property name='dataset_id' type='string' key='dataset_id'>
  656. 知识库 ID
  657. </Property>
  658. <Property name='batch' type='string' key='batch'>
  659. 上传文档的批次号
  660. </Property>
  661. </Properties>
  662. </Col>
  663. <Col sticky>
  664. <CodeGroup
  665. title="Request"
  666. tag="GET"
  667. label="/datasets/{dataset_id}/documents/{batch}/indexing-status"
  668. targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{batch}/indexing-status' \\\n--header 'Authorization: Bearer {api_key}'`}
  669. >
  670. ```bash {{ title: 'cURL' }}
  671. curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{batch}/indexing-status' \
  672. --header 'Authorization: Bearer {api_key}' \
  673. ```
  674. </CodeGroup>
  675. <CodeGroup title="Response">
  676. ```json {{ title: 'Response' }}
  677. {
  678. "data":[{
  679. "id": "",
  680. "indexing_status": "indexing",
  681. "processing_started_at": 1681623462.0,
  682. "parsing_completed_at": 1681623462.0,
  683. "cleaning_completed_at": 1681623462.0,
  684. "splitting_completed_at": 1681623462.0,
  685. "completed_at": null,
  686. "paused_at": null,
  687. "error": null,
  688. "stopped_at": null,
  689. "completed_segments": 24,
  690. "total_segments": 100
  691. }]
  692. }
  693. ```
  694. </CodeGroup>
  695. </Col>
  696. </Row>
  697. <hr className='ml-0 mr-0' />
  698. <Heading
  699. url='/datasets/{dataset_id}/documents/{document_id}'
  700. method='DELETE'
  701. title='删除文档'
  702. name='#delete_document'
  703. />
  704. <Row>
  705. <Col>
  706. ### Path
  707. <Properties>
  708. <Property name='dataset_id' type='string' key='dataset_id'>
  709. 知识库 ID
  710. </Property>
  711. <Property name='document_id' type='string' key='document_id'>
  712. 文档 ID
  713. </Property>
  714. </Properties>
  715. </Col>
  716. <Col sticky>
  717. <CodeGroup
  718. title="Request"
  719. tag="DELETE"
  720. label="/datasets/{dataset_id}/documents/{document_id}"
  721. targetCode={`curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}' \\\n--header 'Authorization: Bearer {api_key}'`}
  722. >
  723. ```bash {{ title: 'cURL' }}
  724. curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}' \
  725. --header 'Authorization: Bearer {api_key}' \
  726. ```
  727. </CodeGroup>
  728. <CodeGroup title="Response">
  729. ```json {{ title: 'Response' }}
  730. {
  731. "result": "success"
  732. }
  733. ```
  734. </CodeGroup>
  735. </Col>
  736. </Row>
  737. <hr className='ml-0 mr-0' />
  738. <Heading
  739. url='/datasets/{dataset_id}/documents'
  740. method='GET'
  741. title='知识库文档列表'
  742. name='#dataset_document_list'
  743. />
  744. <Row>
  745. <Col>
  746. ### Path
  747. <Properties>
  748. <Property name='dataset_id' type='string' key='dataset_id'>
  749. 知识库 ID
  750. </Property>
  751. </Properties>
  752. ### Query
  753. <Properties>
  754. <Property name='keyword' type='string' key='keyword'>
  755. 搜索关键词,可选,目前仅搜索文档名称
  756. </Property>
  757. <Property name='page' type='string' key='page'>
  758. 页码,可选
  759. </Property>
  760. <Property name='limit' type='string' key='limit'>
  761. 返回条数,可选,默认 20,范围 1-100
  762. </Property>
  763. </Properties>
  764. </Col>
  765. <Col sticky>
  766. <CodeGroup
  767. title="Request"
  768. tag="GET"
  769. label="/datasets/{dataset_id}/documents"
  770. targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents' \\\n--header 'Authorization: Bearer {api_key}'`}
  771. >
  772. ```bash {{ title: 'cURL' }}
  773. curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents' \
  774. --header 'Authorization: Bearer {api_key}' \
  775. ```
  776. </CodeGroup>
  777. <CodeGroup title="Response">
  778. ```json {{ title: 'Response' }}
  779. {
  780. "data": [
  781. {
  782. "id": "",
  783. "position": 1,
  784. "data_source_type": "file_upload",
  785. "data_source_info": null,
  786. "dataset_process_rule_id": null,
  787. "name": "dify",
  788. "created_from": "",
  789. "created_by": "",
  790. "created_at": 1681623639,
  791. "tokens": 0,
  792. "indexing_status": "waiting",
  793. "error": null,
  794. "enabled": true,
  795. "disabled_at": null,
  796. "disabled_by": null,
  797. "archived": false
  798. },
  799. ],
  800. "has_more": false,
  801. "limit": 20,
  802. "total": 9,
  803. "page": 1
  804. }
  805. ```
  806. </CodeGroup>
  807. </Col>
  808. </Row>
  809. <hr className='ml-0 mr-0' />
  810. <Heading
  811. url='/datasets/{dataset_id}/documents/{document_id}/segments'
  812. method='POST'
  813. title='新增分段'
  814. name='#create_new_segment'
  815. />
  816. <Row>
  817. <Col>
  818. ### Path
  819. <Properties>
  820. <Property name='dataset_id' type='string' key='dataset_id'>
  821. 知识库 ID
  822. </Property>
  823. <Property name='document_id' type='string' key='document_id'>
  824. 文档 ID
  825. </Property>
  826. </Properties>
  827. ### Request Body
  828. <Properties>
  829. <Property name='segments' type='object list' key='segments'>
  830. - <code>content</code> (text) 文本内容/问题内容,必填
  831. - <code>answer</code> (text) 答案内容,非必填,如果知识库的模式为 Q&A 模式则传值
  832. - <code>keywords</code> (list) 关键字,非必填
  833. </Property>
  834. </Properties>
  835. </Col>
  836. <Col sticky>
  837. <CodeGroup
  838. title="Request"
  839. tag="POST"
  840. label="/datasets/{dataset_id}/documents/{document_id}/segments"
  841. targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{"segments": [{"content": "1","answer": "1","keywords": ["a"]}]}'`}
  842. >
  843. ```bash {{ title: 'cURL' }}
  844. curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments' \
  845. --header 'Authorization: Bearer {api_key}' \
  846. --header 'Content-Type: application/json' \
  847. --data-raw '{
  848. "segments": [
  849. {
  850. "content": "1",
  851. "answer": "1",
  852. "keywords": ["a"]
  853. }
  854. ]
  855. }'
  856. ```
  857. </CodeGroup>
  858. <CodeGroup title="Response">
  859. ```json {{ title: 'Response' }}
  860. {
  861. "data": [{
  862. "id": "",
  863. "position": 1,
  864. "document_id": "",
  865. "content": "1",
  866. "answer": "1",
  867. "word_count": 25,
  868. "tokens": 0,
  869. "keywords": [
  870. "a"
  871. ],
  872. "index_node_id": "",
  873. "index_node_hash": "",
  874. "hit_count": 0,
  875. "enabled": true,
  876. "disabled_at": null,
  877. "disabled_by": null,
  878. "status": "completed",
  879. "created_by": "",
  880. "created_at": 1695312007,
  881. "indexing_at": 1695312007,
  882. "completed_at": 1695312007,
  883. "error": null,
  884. "stopped_at": null
  885. }],
  886. "doc_form": "text_model"
  887. }
  888. ```
  889. </CodeGroup>
  890. </Col>
  891. </Row>
  892. <hr className='ml-0 mr-0' />
  893. <Heading
  894. url='/datasets/{dataset_id}/documents/{document_id}/segments'
  895. method='GET'
  896. title='查询文档分段'
  897. name='#get_segment'
  898. />
  899. <Row>
  900. <Col>
  901. ### Path
  902. <Properties>
  903. <Property name='dataset_id' type='string' key='dataset_id'>
  904. 知识库 ID
  905. </Property>
  906. <Property name='document_id' type='string' key='document_id'>
  907. 文档 ID
  908. </Property>
  909. </Properties>
  910. ### Query
  911. <Properties>
  912. <Property name='keyword' type='string' key='keyword'>
  913. 搜索关键词,可选
  914. </Property>
  915. <Property name='status' type='string' key='status'>
  916. 搜索状态,completed
  917. </Property>
  918. </Properties>
  919. </Col>
  920. <Col sticky>
  921. <CodeGroup
  922. title="Request"
  923. tag="GET"
  924. label="/datasets/{dataset_id}/documents/{document_id}/segments"
  925. targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json'`}
  926. >
  927. ```bash {{ title: 'cURL' }}
  928. curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments' \
  929. --header 'Authorization: Bearer {api_key}' \
  930. --header 'Content-Type: application/json'
  931. ```
  932. </CodeGroup>
  933. <CodeGroup title="Response">
  934. ```json {{ title: 'Response' }}
  935. {
  936. "data": [{
  937. "id": "",
  938. "position": 1,
  939. "document_id": "",
  940. "content": "1",
  941. "answer": "1",
  942. "word_count": 25,
  943. "tokens": 0,
  944. "keywords": [
  945. "a"
  946. ],
  947. "index_node_id": "",
  948. "index_node_hash": "",
  949. "hit_count": 0,
  950. "enabled": true,
  951. "disabled_at": null,
  952. "disabled_by": null,
  953. "status": "completed",
  954. "created_by": "",
  955. "created_at": 1695312007,
  956. "indexing_at": 1695312007,
  957. "completed_at": 1695312007,
  958. "error": null,
  959. "stopped_at": null
  960. }],
  961. "doc_form": "text_model"
  962. }
  963. ```
  964. </CodeGroup>
  965. </Col>
  966. </Row>
  967. <hr className='ml-0 mr-0' />
  968. <Heading
  969. url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}'
  970. method='DELETE'
  971. title='删除文档分段'
  972. name='#delete_segment'
  973. />
  974. <Row>
  975. <Col>
  976. ### Path
  977. <Properties>
  978. <Property name='dataset_id' type='string' key='dataset_id'>
  979. 知识库 ID
  980. </Property>
  981. <Property name='document_id' type='string' key='document_id'>
  982. 文档 ID
  983. </Property>
  984. <Property name='segment_id' type='string' key='segment_id'>
  985. 文档分段ID
  986. </Property>
  987. </Properties>
  988. </Col>
  989. <Col sticky>
  990. <CodeGroup
  991. title="Request"
  992. tag="DELETE"
  993. label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}"
  994. targetCode={`curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json'`}
  995. >
  996. ```bash {{ title: 'cURL' }}
  997. curl --location --request DELETE '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \
  998. --header 'Authorization: Bearer {api_key}' \
  999. --header 'Content-Type: application/json'
  1000. ```
  1001. </CodeGroup>
  1002. <CodeGroup title="Response">
  1003. ```json {{ title: 'Response' }}
  1004. {
  1005. "result": "success"
  1006. }
  1007. ```
  1008. </CodeGroup>
  1009. </Col>
  1010. </Row>
  1011. <hr className='ml-0 mr-0' />
  1012. <Heading
  1013. url='/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}'
  1014. method='POST'
  1015. title='更新文档分段'
  1016. name='#update_segment'
  1017. />
  1018. <Row>
  1019. <Col>
  1020. ### POST
  1021. <Properties>
  1022. <Property name='dataset_id' type='string' key='dataset_id'>
  1023. 知识库 ID
  1024. </Property>
  1025. <Property name='document_id' type='string' key='document_id'>
  1026. 文档 ID
  1027. </Property>
  1028. <Property name='segment_id' type='string' key='segment_id'>
  1029. 文档分段ID
  1030. </Property>
  1031. </Properties>
  1032. ### Request Body
  1033. <Properties>
  1034. <Property name='segment' type='object' key='segment'>
  1035. - <code>content</code> (text) 文本内容/问题内容,必填
  1036. - <code>answer</code> (text) 答案内容,非必填,如果知识库的模式为 Q&A 模式则传值
  1037. - <code>keywords</code> (list) 关键字,非必填
  1038. - <code>enabled</code> (bool) false/true,非必填
  1039. - <code>regenerate_child_chunks</code> (bool) 是否重新生成子分段,非必填
  1040. </Property>
  1041. </Properties>
  1042. </Col>
  1043. <Col sticky>
  1044. <CodeGroup
  1045. title="Request"
  1046. tag="POST"
  1047. label="/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}"
  1048. targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json'\\\n--data-raw '{\"segment\": {\"content\": \"1\",\"answer\": \"1\", \"keywords\": [\"a\"], \"enabled\": false}}'`}
  1049. >
  1050. ```bash {{ title: 'cURL' }}
  1051. curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}' \
  1052. --header 'Authorization: Bearer {api_key}' \
  1053. --header 'Content-Type: application/json' \
  1054. --data-raw '{
  1055. "segment": {
  1056. "content": "1",
  1057. "answer": "1",
  1058. "keywords": ["a"],
  1059. "enabled": false
  1060. }
  1061. }'
  1062. ```
  1063. </CodeGroup>
  1064. <CodeGroup title="Response">
  1065. ```json {{ title: 'Response' }}
  1066. {
  1067. "data": [{
  1068. "id": "",
  1069. "position": 1,
  1070. "document_id": "",
  1071. "content": "1",
  1072. "answer": "1",
  1073. "word_count": 25,
  1074. "tokens": 0,
  1075. "keywords": [
  1076. "a"
  1077. ],
  1078. "index_node_id": "",
  1079. "index_node_hash": "",
  1080. "hit_count": 0,
  1081. "enabled": true,
  1082. "disabled_at": null,
  1083. "disabled_by": null,
  1084. "status": "completed",
  1085. "created_by": "",
  1086. "created_at": 1695312007,
  1087. "indexing_at": 1695312007,
  1088. "completed_at": 1695312007,
  1089. "error": null,
  1090. "stopped_at": null
  1091. }],
  1092. "doc_form": "text_model"
  1093. }
  1094. ```
  1095. </CodeGroup>
  1096. </Col>
  1097. </Row>
  1098. <hr className='ml-0 mr-0' />
  1099. <Heading
  1100. url='/datasets/{dataset_id}/documents/{document_id}/upload-file'
  1101. method='GET'
  1102. title='获取上传文件'
  1103. name='#get_upload_file'
  1104. />
  1105. <Row>
  1106. <Col>
  1107. ### Path
  1108. <Properties>
  1109. <Property name='dataset_id' type='string' key='dataset_id'>
  1110. 知识库 ID
  1111. </Property>
  1112. <Property name='document_id' type='string' key='document_id'>
  1113. 文档 ID
  1114. </Property>
  1115. </Properties>
  1116. </Col>
  1117. <Col sticky>
  1118. <CodeGroup
  1119. title="Request"
  1120. tag="GET"
  1121. label="/datasets/{dataset_id}/documents/{document_id}/upload-file"
  1122. targetCode={`curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/upload-file' \\\n--header 'Authorization: Bearer {api_key}' \\\n--header 'Content-Type: application/json'`}
  1123. >
  1124. ```bash {{ title: 'cURL' }}
  1125. curl --location --request GET '${props.apiBaseUrl}/datasets/{dataset_id}/documents/{document_id}/upload-file' \
  1126. --header 'Authorization: Bearer {api_key}' \
  1127. --header 'Content-Type: application/json'
  1128. ```
  1129. </CodeGroup>
  1130. <CodeGroup title="Response">
  1131. ```json {{ title: 'Response' }}
  1132. {
  1133. "id": "file_id",
  1134. "name": "file_name",
  1135. "size": 1024,
  1136. "extension": "txt",
  1137. "url": "preview_url",
  1138. "download_url": "download_url",
  1139. "mime_type": "text/plain",
  1140. "created_by": "user_id",
  1141. "created_at": 1728734540,
  1142. }
  1143. ```
  1144. </CodeGroup>
  1145. </Col>
  1146. </Row>
  1147. <hr className='ml-0 mr-0' />
  1148. <Heading
  1149. url='/datasets/{dataset_id}/retrieve'
  1150. method='POST'
  1151. title='检索知识库'
  1152. name='#dataset_retrieval'
  1153. />
  1154. <Row>
  1155. <Col>
  1156. ### Path
  1157. <Properties>
  1158. <Property name='dataset_id' type='string' key='dataset_id'>
  1159. 知识库 ID
  1160. </Property>
  1161. </Properties>
  1162. ### Request Body
  1163. <Properties>
  1164. <Property name='query' type='string' key='query'>
  1165. 检索关键词
  1166. </Property>
  1167. <Property name='retrieval_model' type='object' key='retrieval_model'>
  1168. 检索参数(选填,如不填,按照默认方式召回)
  1169. - <code>search_method</code> (text) 检索方法:以下三个关键字之一,必填
  1170. - <code>keyword_search</code> 关键字检索
  1171. - <code>semantic_search</code> 语义检索
  1172. - <code>full_text_search</code> 全文检索
  1173. - <code>hybrid_search</code> 混合检索
  1174. - <code>reranking_enable</code> (bool) 是否启用 Reranking,非必填,如果检索模式为 semantic_search 模式或者 hybrid_search 则传值
  1175. - <code>reranking_mode</code> (object) Rerank 模型配置,非必填,如果启用了 reranking 则传值
  1176. - <code>reranking_provider_name</code> (string) Rerank 模型提供商
  1177. - <code>reranking_model_name</code> (string) Rerank 模型名称
  1178. - <code>weights</code> (float) 混合检索模式下语意检索的权重设置
  1179. - <code>top_k</code> (integer) 返回结果数量,非必填
  1180. - <code>score_threshold_enabled</code> (bool) 是否开启 score 阈值
  1181. - <code>score_threshold</code> (float) Score 阈值
  1182. </Property>
  1183. <Property name='external_retrieval_model' type='object' key='external_retrieval_model'>
  1184. 未启用字段
  1185. </Property>
  1186. </Properties>
  1187. </Col>
  1188. <Col sticky>
  1189. <CodeGroup
  1190. title="Request"
  1191. tag="POST"
  1192. label="/datasets/{dataset_id}/retrieve"
  1193. targetCode={`curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/retrieve' \\\n--header 'Authorization: Bearer {api_key}'\\\n--header 'Content-Type: application/json'\\\n--data-raw '{
  1194. "query": "test",
  1195. "retrieval_model": {
  1196. "search_method": "keyword_search",
  1197. "reranking_enable": false,
  1198. "reranking_mode": null,
  1199. "reranking_model": {
  1200. "reranking_provider_name": "",
  1201. "reranking_model_name": ""
  1202. },
  1203. "weights": null,
  1204. "top_k": 1,
  1205. "score_threshold_enabled": false,
  1206. "score_threshold": null
  1207. }
  1208. }'`}
  1209. >
  1210. ```bash {{ title: 'cURL' }}
  1211. curl --location --request POST '${props.apiBaseUrl}/datasets/{dataset_id}/retrieve' \
  1212. --header 'Authorization: Bearer {api_key}' \
  1213. --header 'Content-Type: application/json' \
  1214. --data-raw '{
  1215. "query": "test",
  1216. "retrieval_model": {
  1217. "search_method": "keyword_search",
  1218. "reranking_enable": false,
  1219. "reranking_mode": null,
  1220. "reranking_model": {
  1221. "reranking_provider_name": "",
  1222. "reranking_model_name": ""
  1223. },
  1224. "weights": null,
  1225. "top_k": 2,
  1226. "score_threshold_enabled": false,
  1227. "score_threshold": null
  1228. }
  1229. }'
  1230. ```
  1231. </CodeGroup>
  1232. <CodeGroup title="Response">
  1233. ```json {{ title: 'Response' }}
  1234. {
  1235. "query": {
  1236. "content": "test"
  1237. },
  1238. "records": [
  1239. {
  1240. "segment": {
  1241. "id": "7fa6f24f-8679-48b3-bc9d-bdf28d73f218",
  1242. "position": 1,
  1243. "document_id": "a8c6c36f-9f5d-4d7a-8472-f5d7b75d71d2",
  1244. "content": "Operation guide",
  1245. "answer": null,
  1246. "word_count": 847,
  1247. "tokens": 280,
  1248. "keywords": [
  1249. "install",
  1250. "java",
  1251. "base",
  1252. "scripts",
  1253. "jdk",
  1254. "manual",
  1255. "internal",
  1256. "opens",
  1257. "add",
  1258. "vmoptions"
  1259. ],
  1260. "index_node_id": "39dd8443-d960-45a8-bb46-7275ad7fbc8e",
  1261. "index_node_hash": "0189157697b3c6a418ccf8264a09699f25858975578f3467c76d6bfc94df1d73",
  1262. "hit_count": 0,
  1263. "enabled": true,
  1264. "disabled_at": null,
  1265. "disabled_by": null,
  1266. "status": "completed",
  1267. "created_by": "dbcb1ab5-90c8-41a7-8b78-73b235eb6f6f",
  1268. "created_at": 1728734540,
  1269. "indexing_at": 1728734552,
  1270. "completed_at": 1728734584,
  1271. "error": null,
  1272. "stopped_at": null,
  1273. "document": {
  1274. "id": "a8c6c36f-9f5d-4d7a-8472-f5d7b75d71d2",
  1275. "data_source_type": "upload_file",
  1276. "name": "readme.txt",
  1277. "doc_type": null
  1278. }
  1279. },
  1280. "score": 3.730463140527718e-05,
  1281. "tsne_position": null
  1282. }
  1283. ]
  1284. }
  1285. ```
  1286. </CodeGroup>
  1287. </Col>
  1288. </Row>
  1289. <hr className='ml-0 mr-0' />
  1290. <Row>
  1291. <Col>
  1292. ### 错误信息
  1293. <Properties>
  1294. <Property name='code' type='string' key='code'>
  1295. 返回的错误代码
  1296. </Property>
  1297. </Properties>
  1298. <Properties>
  1299. <Property name='status' type='number' key='status'>
  1300. 返回的错误状态
  1301. </Property>
  1302. </Properties>
  1303. <Properties>
  1304. <Property name='message' type='string' key='message'>
  1305. 返回的错误信息
  1306. </Property>
  1307. </Properties>
  1308. </Col>
  1309. <Col>
  1310. <CodeGroup title="Example">
  1311. ```json {{ title: 'Response' }}
  1312. {
  1313. "code": "no_file_uploaded",
  1314. "message": "Please upload your file.",
  1315. "status": 400
  1316. }
  1317. ```
  1318. </CodeGroup>
  1319. </Col>
  1320. </Row>
  1321. <table className="max-w-auto border-collapse border border-slate-400" style={{ maxWidth: 'none', width: 'auto' }}>
  1322. <thead style={{ background: '#f9fafc' }}>
  1323. <tr>
  1324. <th className="p-2 border border-slate-300">code</th>
  1325. <th className="p-2 border border-slate-300">status</th>
  1326. <th className="p-2 border border-slate-300">message</th>
  1327. </tr>
  1328. </thead>
  1329. <tbody>
  1330. <tr>
  1331. <td className="p-2 border border-slate-300">no_file_uploaded</td>
  1332. <td className="p-2 border border-slate-300">400</td>
  1333. <td className="p-2 border border-slate-300">Please upload your file.</td>
  1334. </tr>
  1335. <tr>
  1336. <td className="p-2 border border-slate-300">too_many_files</td>
  1337. <td className="p-2 border border-slate-300">400</td>
  1338. <td className="p-2 border border-slate-300">Only one file is allowed.</td>
  1339. </tr>
  1340. <tr>
  1341. <td className="p-2 border border-slate-300">file_too_large</td>
  1342. <td className="p-2 border border-slate-300">413</td>
  1343. <td className="p-2 border border-slate-300">File size exceeded.</td>
  1344. </tr>
  1345. <tr>
  1346. <td className="p-2 border border-slate-300">unsupported_file_type</td>
  1347. <td className="p-2 border border-slate-300">415</td>
  1348. <td className="p-2 border border-slate-300">File type not allowed.</td>
  1349. </tr>
  1350. <tr>
  1351. <td className="p-2 border border-slate-300">high_quality_dataset_only</td>
  1352. <td className="p-2 border border-slate-300">400</td>
  1353. <td className="p-2 border border-slate-300">Current operation only supports 'high-quality' datasets.</td>
  1354. </tr>
  1355. <tr>
  1356. <td className="p-2 border border-slate-300">dataset_not_initialized</td>
  1357. <td className="p-2 border border-slate-300">400</td>
  1358. <td className="p-2 border border-slate-300">The dataset is still being initialized or indexing. Please wait a moment.</td>
  1359. </tr>
  1360. <tr>
  1361. <td className="p-2 border border-slate-300">archived_document_immutable</td>
  1362. <td className="p-2 border border-slate-300">403</td>
  1363. <td className="p-2 border border-slate-300">The archived document is not editable.</td>
  1364. </tr>
  1365. <tr>
  1366. <td className="p-2 border border-slate-300">dataset_name_duplicate</td>
  1367. <td className="p-2 border border-slate-300">409</td>
  1368. <td className="p-2 border border-slate-300">The dataset name already exists. Please modify your dataset name.</td>
  1369. </tr>
  1370. <tr>
  1371. <td className="p-2 border border-slate-300">invalid_action</td>
  1372. <td className="p-2 border border-slate-300">400</td>
  1373. <td className="p-2 border border-slate-300">Invalid action.</td>
  1374. </tr>
  1375. <tr>
  1376. <td className="p-2 border border-slate-300">document_already_finished</td>
  1377. <td className="p-2 border border-slate-300">400</td>
  1378. <td className="p-2 border border-slate-300">The document has been processed. Please refresh the page or go to the document details.</td>
  1379. </tr>
  1380. <tr>
  1381. <td className="p-2 border border-slate-300">document_indexing</td>
  1382. <td className="p-2 border border-slate-300">400</td>
  1383. <td className="p-2 border border-slate-300">The document is being processed and cannot be edited.</td>
  1384. </tr>
  1385. <tr>
  1386. <td className="p-2 border border-slate-300">invalid_metadata</td>
  1387. <td className="p-2 border border-slate-300">400</td>
  1388. <td className="p-2 border border-slate-300">The metadata content is incorrect. Please check and verify.</td>
  1389. </tr>
  1390. </tbody>
  1391. </table>
  1392. <div className="pb-4" />