template.zh.mdx 50 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451
  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" />