用文本更新文档

post/datasets/{dataset_id}/documents/{document_id}/update-by-text

Request example

curl --request POST \
  --url https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "doc_form": "text_model",
  "doc_language": "English",
  "name": "<string>",
  "process_rule": {
    "mode": "automatic",
    "rules": {
      "pre_processing_rules": [
        {
          "enabled": true,
          "id": "remove_stopwords"
        }
      ],
      "segmentation": {
        "chunk_overlap": 0,
        "max_tokens": 1,
        "separator": "\n"
      }
    }
  },
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  },
  "text": "<string>"
}'

import requests

url = "https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "doc_form": "text_model",
    "doc_language": "English",
    "name": "<string>",
    "process_rule": {
        "mode": "automatic",
        "rules": {
            "pre_processing_rules": [
                {
                    "enabled": True,
                    "id": "remove_stopwords"
                }
            ],
            "segmentation": {
                "chunk_overlap": 0,
                "max_tokens": 1,
                "separator": "
"
            }
        }
    },
    "retrieval_model": {
        "metadata_filtering_conditions": {
            "conditions": [
                {
                    "comparison_operator": "contains",
                    "name": "<string>",
                    "value": "<string>"
                }
            ],
            "logical_operator": "and"
        },
        "reranking_enable": True,
        "reranking_mode": "reranking_model",
        "reranking_model": {
            "reranking_model_name": "<string>",
            "reranking_provider_name": "<string>"
        },
        "score_threshold": 1,
        "score_threshold_enabled": True,
        "search_method": "keyword_search",
        "top_k": 1,
        "weights": {
            "keyword_setting": {
                "keyword_weight": 1
            },
            "vector_setting": {
                "embedding_model_name": "<string>",
                "embedding_provider_name": "<string>",
                "vector_weight": 1
            },
            "weight_type": "semantic_first"
        }
    },
    "text": "<string>"
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "doc_form": "text_model",
    "doc_language": "English",
    "name": "<string>",
    "process_rule": {
      "mode": "automatic",
      "rules": {
        "pre_processing_rules": [
          {
            "enabled": true,
            "id": "remove_stopwords"
          }
        ],
        "segmentation": {
          "chunk_overlap": 0,
          "max_tokens": 1,
          "separator": "\n"
        }
      }
    },
    "retrieval_model": {
      "metadata_filtering_conditions": {
        "conditions": [
          {
            "comparison_operator": "contains",
            "name": "<string>",
            "value": "<string>"
          }
        ],
        "logical_operator": "and"
      },
      "reranking_enable": true,
      "reranking_mode": "reranking_model",
      "reranking_model": {
        "reranking_model_name": "<string>",
        "reranking_provider_name": "<string>"
      },
      "score_threshold": 1,
      "score_threshold_enabled": true,
      "search_method": "keyword_search",
      "top_k": 1,
      "weights": {
        "keyword_setting": {
          "keyword_weight": 1
        },
        "vector_setting": {
          "embedding_model_name": "<string>",
          "embedding_provider_name": "<string>",
          "vector_weight": 1
        },
        "weight_type": "semantic_first"
      }
    },
    "text": "<string>"
  })
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "doc_form": "text_model",
  "doc_language": "English",
  "name": "<string>",
  "process_rule": {
    "mode": "automatic",
    "rules": {
      "pre_processing_rules": [
        {
          "enabled": true,
          "id": "remove_stopwords"
        }
      ],
      "segmentation": {
        "chunk_overlap": 0,
        "max_tokens": 1,
        "separator": "\\n"
      }
    }
  },
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  },
  "text": "<string>"
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text"
	payload := strings.NewReader("{\n  \"doc_form\": \"text_model\",\n  \"doc_language\": \"English\",\n  \"name\": \"<string>\",\n  \"process_rule\": {\n    \"mode\": \"automatic\",\n    \"rules\": {\n      \"pre_processing_rules\": [\n        {\n          \"enabled\": true,\n          \"id\": \"remove_stopwords\"\n        }\n      ],\n      \"segmentation\": {\n        \"chunk_overlap\": 0,\n        \"max_tokens\": 1,\n        \"separator\": \"\\n\"\n      }\n    }\n  },\n  \"retrieval_model\": {\n    \"metadata_filtering_conditions\": {\n      \"conditions\": [\n        {\n          \"comparison_operator\": \"contains\",\n          \"name\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"logical_operator\": \"and\"\n    },\n    \"reranking_enable\": true,\n    \"reranking_mode\": \"reranking_model\",\n    \"reranking_model\": {\n      \"reranking_model_name\": \"<string>\",\n      \"reranking_provider_name\": \"<string>\"\n    },\n    \"score_threshold\": 1,\n    \"score_threshold_enabled\": true,\n    \"search_method\": \"keyword_search\",\n    \"top_k\": 1,\n    \"weights\": {\n      \"keyword_setting\": {\n        \"keyword_weight\": 1\n      },\n      \"vector_setting\": {\n        \"embedding_model_name\": \"<string>\",\n        \"embedding_provider_name\": \"<string>\",\n        \"vector_weight\": 1\n      },\n      \"weight_type\": \"semantic_first\"\n    }\n  },\n  \"text\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"doc_form\": \"text_model\",\n  \"doc_language\": \"English\",\n  \"name\": \"<string>\",\n  \"process_rule\": {\n    \"mode\": \"automatic\",\n    \"rules\": {\n      \"pre_processing_rules\": [\n        {\n          \"enabled\": true,\n          \"id\": \"remove_stopwords\"\n        }\n      ],\n      \"segmentation\": {\n        \"chunk_overlap\": 0,\n        \"max_tokens\": 1,\n        \"separator\": \"\\n\"\n      }\n    }\n  },\n  \"retrieval_model\": {\n    \"metadata_filtering_conditions\": {\n      \"conditions\": [\n        {\n          \"comparison_operator\": \"contains\",\n          \"name\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"logical_operator\": \"and\"\n    },\n    \"reranking_enable\": true,\n    \"reranking_mode\": \"reranking_model\",\n    \"reranking_model\": {\n      \"reranking_model_name\": \"<string>\",\n      \"reranking_provider_name\": \"<string>\"\n    },\n    \"score_threshold\": 1,\n    \"score_threshold_enabled\": true,\n    \"search_method\": \"keyword_search\",\n    \"top_k\": 1,\n    \"weights\": {\n      \"keyword_setting\": {\n        \"keyword_weight\": 1\n      },\n      \"vector_setting\": {\n        \"embedding_model_name\": \"<string>\",\n        \"embedding_provider_name\": \"<string>\",\n        \"vector_weight\": 1\n      },\n      \"weight_type\": \"semantic_first\"\n    }\n  },\n  \"text\": \"<string>\"\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "doc_form": "text_model",
  "doc_language": "English",
  "name": "<string>",
  "process_rule": {
    "mode": "automatic",
    "rules": {
      "pre_processing_rules": [
        {
          "enabled": true,
          "id": "remove_stopwords"
        }
      ],
      "segmentation": {
        "chunk_overlap": 0,
        "max_tokens": 1,
        "separator": "\\n"
      }
    }
  },
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  },
  "text": "<string>"
}'

response = http.request(request)
puts response.read_body

Response

{
  "batch": "20250306150245647595",
  "document": {
    "archived": false,
    "created_at": 1741267200,
    "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
    "created_from": "api",
    "data_source_detail_dict": {
      "upload_file": {
        "created_at": 1741267200,
        "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
        "extension": "txt",
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "mime_type": "text/plain",
        "name": "guide.txt",
        "size": 2048
      }
    },
    "data_source_info": {
      "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "data_source_type": "upload_file",
    "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
    "disabled_at": null,
    "disabled_by": null,
    "display_status": "available",
    "doc_form": "text_model",
    "doc_metadata": [],
    "enabled": true,
    "error": null,
    "hit_count": 0,
    "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
    "indexing_status": "completed",
    "name": "guide.txt",
    "need_summary": false,
    "position": 1,
    "summary_index_status": null,
    "tokens": 512,
    "word_count": 350
  }
}

{
  "code": "invalid_param",
  "message": "name is required when text is provided.",
  "status": 400
}

{
  "code": "invalid_param",
  "message": "Document is not available",
  "status": 400
}

{
  "code": "provider_not_initialize",
  "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.",
  "status": 400
}

{
  "code": "forbidden",
  "message": "Dataset api access is not enabled.",
  "status": 403
}

{
  "code": "forbidden",
  "message": "The capacity of the vector space has reached the limit of your subscription.",
  "status": 403
}

{
  "code": "forbidden",
  "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
  "status": 403
}

{
  "code": "forbidden",
  "message": "The API key is not authorized to access this knowledge base.",
  "status": 403
}

{
  "code": "not_found",
  "message": "Dataset not found.",
  "status": 404
}

{
  "code": "not_found",
  "message": "Document not found.",
  "status": 404
}

{
  "code": "service_unavailable",
  "message": "Unable to verify vector space usage right now. Please try again later.",
  "status": 503
}

post/datasets/{dataset_id}/documents/{document_id}/update-by-text

Authorization

Authorizationstringheaderrequired#

每个请求都通过 API Key 认证：Authorization: Bearer {API_KEY}。应用接口使用应用 API Key，知识库接口使用知识库 API Key（快速开始）。

API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP 401（unauthorized）。

Path parameters

dataset_idstringrequired#

知识库 ID，通过获取知识库列表获取。使用限定范围的密钥时，从 Dify 页面 URL 复制 ID。

document_idstringrequired#

文档 ID。从获取知识库的文档列表获取。

Body

application/json

doc_formenum<string>#

text_model 为标准文本分段，hierarchical_model 为父子分段结构，qa_model 为问答对提取。

Default: "text_model"

Options:text_modelhierarchical_modelqa_model

doc_languagestring#

用于处理优化的文档语言。

Default: "English"

namestring#

文档名称。当提供 text 时必填。

process_ruleobject#

分块处理规则。

Show child attributes

modeenum<string>required#

automatic 使用内置规则，custom 允许手动配置，hierarchical 启用父子分段结构（配合 doc_form: hierarchical_model 使用）。

Options:automaticcustomhierarchical

rulesobject#

Show child attributes

pre_processing_rulesobject[]#

Show child attributes

enabledboolean#

该预处理规则是否启用。

idenum<string>#

规则标识符。

Options:remove_stopwordsremove_extra_spacesremove_urls_emails

segmentationobject#

Show child attributes

chunk_overlapinteger#

分段之间的令牌重叠数。

Default: 0

max_tokensinteger#

每个分段的最大令牌数。

separatorstring#

用于拆分文本的自定义分隔符。

Default: "\n"

retrieval_modelobject#

Show child attributes

metadata_filtering_conditionsobject#

仅检索文档元数据匹配指定条件的分段。条件由服务端基于文档元数据字段评估。

Show child attributes

conditionsobject[]#

要评估的元数据条件列表。

Show child attributes

comparison_operatorenum<string>required#

按元数据类型选择要应用的比较方式：

字符串或数组类型元数据：contains、not contains、start with、end with、is、is not、empty、not empty、in、not in
数值类型元数据：=、≠、>、<、≥、≤
时间类型元数据：before、after

Options:containsnot containsstart withend withisis notemptynot emptyinnot in=≠><≥≤beforeafter

namestringrequired#

用于比较的元数据字段名称。

valuestring · string[] · number#

用于比较的值。类型取决于 comparison_operator：大多数字符串运算符使用字符串；in 和 not in 使用字符串数组；数值运算符使用数字；empty 和 not empty 时省略。

logical_operatorenum<string>#

多个条件之间的组合方式。

Default: "and"

Options:andor

reranking_enablebooleanrequired#

是否启用重排序。

reranking_modeenum<string>#

重排序模式。当 reranking_enable 为 true 时必填。

Options:reranking_modelweighted_score

reranking_modelobject#

重排序模型配置。

Show child attributes

reranking_model_namestring#

重排序模型名称。

reranking_provider_namestring#

重排序模型供应商标识符，格式为 organization/plugin_name/provider_name（例如 langgenius/cohere/cohere）。cohere 这类简写会展开为 langgenius/<name>/<name>，仅对 langgenius 发布的插件有效。

有效取值从获取可用模型中 model_type=rerank 返回的 provider 字段获取。

score_thresholdnumber#

结果的最低相关性分数。仅在 score_threshold_enabled 为 true 时生效。

score_threshold_enabledbooleanrequired#

是否启用分数阈值过滤。

search_methodenum<string>required#

用于检索的搜索方法。

Options:keyword_searchsemantic_searchfull_text_searchhybrid_search

top_kintegerrequired#

返回的最大结果数。

weightsobject#

混合搜索的权重配置。

Show child attributes

keyword_settingobject#

关键词搜索权重设置。

Show child attributes

keyword_weightnumber#

分配给关键词搜索结果的权重。

vector_settingobject#

语义搜索权重设置。

Show child attributes

embedding_model_namestring#

用于向量搜索的嵌入模型名称。

embedding_provider_namestring#

用于向量搜索的嵌入模型供应商。

vector_weightnumber#

分配给语义（向量）搜索结果的权重。

weight_typeenum<string>#

平衡语义搜索和关键词搜索权重的策略。

Options:semantic_firstkeyword_firstcustomized

textstring#

文档文本内容。

Responses

application/json

文档更新成功。

batchstring#

用于跟踪索引进度的批次 ID。

documentobject#

Show child attributes

archivedboolean#

文档是否已归档。

created_atnumber#

创建时间戳（Unix 纪元，单位为秒）。

created_bystring#

创建该文档的用户 ID。

created_fromstring#

文档来源。通过 API 创建时为 api，通过 UI 创建时为 web。

data_source_detail_dictobject#

详细的数据源信息，包括文件详情。

data_source_infoobject#

原始数据源信息，随 data_source_type 而异。

data_source_typestring#

文档的创建方式。文件上传为 upload_file，Notion 导入为 notion_import。

dataset_process_rule_idstring#

应用于该文档的处理规则 ID。

disabled_atnumber#

文档被禁用的时间戳。启用时为 null。

disabled_bystring#

禁用该文档的用户 ID。启用时为 null。

display_statusstring#

基于 indexing_status 和 enabled 状态派生的面向用户的显示状态。

doc_formstring#

文档分块模式。text_model 表示标准文本分块，hierarchical_model 表示父子结构，qa_model 表示问答对提取。

doc_metadataobject[]#

分配给该文档的元数据值。

Show child attributes

idstring#

元数据字段标识符。

namestring#

元数据字段名称。

typestring#

元数据字段值类型。

valuestring#

此文档的元数据值。

enabledboolean#

该文档是否启用检索。

errorstring#

索引失败时的错误消息。无错误时为 null。

hit_countinteger#

该文档在检索查询中被匹配的次数。

idstring#

文档的唯一标识符。

indexing_statusstring#

当前索引状态。waiting 表示排队中，parsing 表示正在提取内容，cleaning 表示正在去噪，splitting 表示正在分块，indexing 表示正在构建向量，completed 表示就绪，error 表示失败，paused 表示手动暂停。

namestring#

文档名称。

need_summaryboolean#

是否需要为该文档生成摘要。

positioninteger#

文档在列表中的显示位置。

summary_index_statusstring#

该文档的摘要索引状态。未配置摘要索引时为 null。

tokensinteger#

文档中的令牌总数。

word_countinteger#

文档的总字数。

获取文档嵌入状态（进度）用文件更新文档