langgenius/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-07-22 04:15:24 -04:00
Code Issues 10 Packages Projects Releases Wiki Activity

[DOCS]: API Documentation Error: Incorrect Description and cURL Example for the reranking_mode Parameter in the "Create an Empty Knowledge Base" Interface! #297

New Issue
Closed
opened 2026-02-16 05:19:48 -05:00 by yindo · 2 comments
yindo commented 2026-02-16 05:19:48 -05:00
Owner
Copy Link
Copy Source

Originally created by @Guofu1149 on GitHub (Dec 30, 2025).

Type of Documentation Change

Error/Typo fix

Documentation Page URL or Path

https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-provider-name

Current Content

Problem Description:
API Documentation Error: Incorrect Description and cURL Example for the reranking_mode Parameter in the "Create an Empty Knowledge Base" Interface!
When using the /v1/datasets API to create an empty knowledge base, it was discovered that the description of the retrieval_model.reranking_mode parameter in the official documentation does not match the actual required format.

Specific page URL: https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-provider-name

Current Content

Image

Official parameter Specific(wrong):
retrieval_model
object

Hide child attributes
​
retrieval_model.search_method
enum

The search method to use for retrieval.
Available options: hybrid_search,
semantic_search,
full_text_search,
keyword_search
​
retrieval_model.reranking_enable
boolean

Whether to enable a reranking model to improve search results.
​
retrieval_model.reranking_mode
object

Configuration for the reranking model.

Hide child attributes
​
retrieval_model.reranking_mode.reranking_provider_name
string

The provider of the rerank model.
​
retrieval_model.reranking_mode.reranking_model_name
string

The name of the rerank model.
​
retrieval_model.top_k
integer

The number of top matching results to return.
​
retrieval_model.score_threshold_enabled
boolean

Whether to apply a score threshold to filter results.
​
retrieval_model.score_threshold
number | null

The minimum score for a result to be included.
​
retrieval_model.weights
number | null

The weight of semantic search in a hybrid search mode.
retrieval_model.search_method
enum

The search method to use for retrieval.
Available options: hybrid_search,
semantic_search,
full_text_search,
keyword_search
​
retrieval_model.reranking_enable
boolean

Whether to enable a reranking model to improve search results.
​
retrieval_model.reranking_mode
object

Configuration for the reranking model.

Hide child attributes
​
retrieval_model.reranking_mode.reranking_provider_name
string

The provider of the rerank model.
​
retrieval_model.reranking_mode.reranking_model_name
string

The name of the rerank model.
retrieval_model.reranking_mode.reranking_provider_name
string

The provider of the rerank model.
​
retrieval_model.reranking_mode.reranking_model_name
string

The name of the rerank model.

official curl example(wrong):
curl --request POST
--url https://api.dify.ai/v1/datasets
--header 'Authorization: Bearer '
--header 'Content-Type: application/json'
--data '
{
"name": "",
"description": "",
"indexing_technique": "high_quality",
"permission": "only_me",
"provider": "vendor",
"external_knowledge_api_id": "",
"external_knowledge_id": "",
"embedding_model": "",
"embedding_model_provider": "",
"retrieval_model": {
"search_method": "hybrid_search",
"reranking_enable": true,
"reranking_mode": {
"reranking_provider_name": "",
"reranking_model_name": ""
},
"top_k": 123,
"score_threshold_enabled": true,
"score_threshold": 123,
"weights": 123
}
}
'

Reproduction Steps:

  1. Send a request following the cURL example in the official documentation:

    "retrieval_model": {
  "search_method": "hybrid_search",
  "reranking_enable": true,
  "reranking_mode": {
    "reranking_provider_name": "<string>",
    "reranking_model_name": "<string>"
  },
  ...
}

  2. Receive a 400 error:

    1 validation error for DatasetCreatePayload
retrieval_model.reranking_mode
  Input should be a valid string [type=string_type, input_value={...}, input_type=dict]

Actual Correct Configuration:

By creating a knowledge base via the web UI and examining the actual parameters, the correct configuration should be:

"retrieval_model_dict": {
  "search_method": "semantic_search",
  "reranking_enable": true,
  "reranking_mode": null,  // Should be null or a string
  "reranking_model": {      // The actual rerank configuration field
    "reranking_provider_name": "langgenius/xinference/xinference",
    "reranking_model_name": "Qwen3-Reranker-4B"
  },
  ...
}

Problem Analysis:

  1. Documentation Error: The documentation describes reranking_mode as an object, but the actual API expects it to be a string (or null).
  2. Field Confusion: The actual rerank configuration should use the reranking_model field, not the configuration placed within reranking_mode.
  3. Inconsistent Field Names: The field name in the response is retrieval_model_dict, while it should be retrieval_model in the request.

Suggested Fixes:

  1. Update API Documentation: Change the description of reranking_mode from "object" to "string | null".
  2. Add Correct Example: Include a correct example of using the reranking_model field in the documentation: 
    "retrieval_model": {
  "search_method": "hybrid_search",
  "reranking_enable": true,
  "reranking_mode": null,
  "reranking_model": {
    "reranking_provider_name": "<string>",
    "reranking_model_name": "<string>"
  },
  ...
}
  3. Clarify Field Usage: Explain the difference and correct usage between reranking_mode and reranking_model.

Environment Information:

Additional Information:

This issue prevents developers from successfully creating a knowledge base with rerank configuration as per the documentation, requiring additional debugging and reverse engineering to find the correct parameter format.

This issue clearly identifies the problem, provides a comparison between the error and the correct format, and offers specific suggestions for fixes, which will help the development team quickly locate and resolve the documentation error.

Suggested Changes

Suggested Fixes:

  1. Update API Documentation: Change the description of reranking_mode from "object" to "string | null".
  2. Add Correct Example: Include a correct example of using the reranking_model field in the documentation: 
    "retrieval_model": {
  "search_method": "hybrid_search",
  "reranking_enable": true,
  "reranking_mode": null,
  "reranking_model": {
    "reranking_provider_name": "<string>",
    "reranking_model_name": "<string>"
  },
  ...
}

Corrected Valid Request Body Example:

{
  "name": "Test Knowledge Base",
  "description": "For testing",
  "indexing_technique": "high_quality",
  "permission": "only_me",
  "provider": "vendor",
  "embedding_model": "dengcao/Qwen3-Embedding-8B:Q4_K_M",
  "embedding_model_provider": "langgenius/ollama/ollama",
  "retrieval_model": {
    "search_method": "semantic_search",
    "reranking_enable": true,
    "reranking_mode": null,
    "reranking_model": {
      "reranking_provider_name": "langgenius/xinference/xinference",
      "reranking_model_name": "Qwen3-Reranker-4B"
    },
    "top_k": 3,
    "score_threshold_enabled": false,
    "score_threshold": 0.5
  }
}


### Reason for Change

API Documentation Error: Incorrect Description and cURL Example for the `reranking_mode` Parameter in the "Create an Empty Knowledge Base" Interface!
When using the `/v1/datasets` API to create an empty knowledge base, it was discovered that the description of the `retrieval_model.reranking_mode` parameter in the official documentation does not match the actual required format.

Specific page URL: https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-provider-name

**Reproduction Steps:**

1. Send a request following the cURL example in the [official documentation](https://docs.dify.ai/developers/apis#tag/Datasets/operation/create-dataset):
   ```json
   "retrieval_model": {
     "search_method": "hybrid_search",
     "reranking_enable": true,
     "reranking_mode": {
       "reranking_provider_name": "<string>",
       "reranking_model_name": "<string>"
     },
     ...
   }
  1. Receive a 400 error: 
    1 validation error for DatasetCreatePayload
retrieval_model.reranking_mode
  Input should be a valid string [type=string_type, input_value={...}, input_type=dict]

Actual Correct Configuration:

By creating a knowledge base via the web UI and examining the actual parameters, the correct configuration should be:

"retrieval_model_dict": {
  "search_method": "semantic_search",
  "reranking_enable": true,
  "reranking_mode": null,  // Should be null or a string
  "reranking_model": {      // The actual rerank configuration field
    "reranking_provider_name": "langgenius/xinference/xinference",
    "reranking_model_name": "Qwen3-Reranker-4B"
  },
  ...
}

Problem Analysis:

  1. Documentation Error: The documentation describes reranking_mode as an object, but the actual API expects it to be a string (or null).
  2. Field Confusion: The actual rerank configuration should use the reranking_model field, not the configuration placed within reranking_mode.
  3. Inconsistent Field Names: The field name in the response is retrieval_model_dict, while it should be retrieval_model in the request.

Code of Conduct

  • I agree to follow Dify's documentation contribution guidelines
  • I have searched for existing issues search for existing issues, including closed ones.
  • I confirm that I am using English to submit this report, otherwise it will be closed.
  • 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）
  • Please do not modify this template :) and fill in all the required fields.
Originally created by @Guofu1149 on GitHub (Dec 30, 2025). ### Type of Documentation Change Error/Typo fix ### Documentation Page URL or Path https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-provider-name ### Current Content **Problem Description:** API Documentation Error: Incorrect Description and cURL Example for the `reranking_mode` Parameter in the "Create an Empty Knowledge Base" Interface! When using the `/v1/datasets` API to create an empty knowledge base, it was discovered that the description of the `retrieval_model.reranking_mode` parameter in the official documentation does not match the actual required format. Specific page URL: https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-provider-name **Current Content** <img width="1281" height="812" alt="Image" src="https://github.com/user-attachments/assets/04349758-b5b9-4374-be60-b3294844430a" /> *Official parameter Specific(wrong):* retrieval_model object Hide child attributes [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-search-method) retrieval_model.search_method enum<string> The search method to use for retrieval. Available options: hybrid_search, semantic_search, full_text_search, keyword_search [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-enable) retrieval_model.reranking_enable boolean Whether to enable a reranking model to improve search results. [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0) retrieval_model.reranking_mode object Configuration for the reranking model. Hide child attributes [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-provider-name) retrieval_model.reranking_mode.reranking_provider_name string The provider of the rerank model. [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-model-name) retrieval_model.reranking_mode.reranking_model_name string The name of the rerank model. [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-top-k) retrieval_model.top_k integer The number of top matching results to return. [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-score-threshold-enabled) retrieval_model.score_threshold_enabled boolean Whether to apply a score threshold to filter results. [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-score-threshold-one-of-0) retrieval_model.score_threshold number<float> | null The minimum score for a result to be included. [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-weights-one-of-0) retrieval_model.weights number<float> | null The weight of semantic search in a hybrid search mode. retrieval_model.search_method enum<string> The search method to use for retrieval. Available options: hybrid_search, semantic_search, full_text_search, keyword_search [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-enable) retrieval_model.reranking_enable boolean Whether to enable a reranking model to improve search results. [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0) retrieval_model.reranking_mode object Configuration for the reranking model. Hide child attributes [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-provider-name) retrieval_model.reranking_mode.reranking_provider_name string The provider of the rerank model. [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-model-name) retrieval_model.reranking_mode.reranking_model_name string The name of the rerank model. retrieval_model.reranking_mode.reranking_provider_name string The provider of the rerank model. [​](https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-model-name) retrieval_model.reranking_mode.reranking_model_name string The name of the rerank model. *official curl example(wrong):* curl --request POST \ --url https://api.dify.ai/v1/datasets \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "name": "<string>", "description": "<string>", "indexing_technique": "high_quality", "permission": "only_me", "provider": "vendor", "external_knowledge_api_id": "<string>", "external_knowledge_id": "<string>", "embedding_model": "<string>", "embedding_model_provider": "<string>", "retrieval_model": { "search_method": "hybrid_search", "reranking_enable": true, "reranking_mode": { "reranking_provider_name": "<string>", "reranking_model_name": "<string>" }, "top_k": 123, "score_threshold_enabled": true, "score_threshold": 123, "weights": 123 } } ' **Reproduction Steps:** 1. Send a request following the cURL example in the [official documentation](https://docs.dify.ai/developers/apis#tag/Datasets/operation/create-dataset): ```json "retrieval_model": { "search_method": "hybrid_search", "reranking_enable": true, "reranking_mode": { "reranking_provider_name": "<string>", "reranking_model_name": "<string>" }, ... } ``` 2. Receive a 400 error: ``` 1 validation error for DatasetCreatePayload retrieval_model.reranking_mode Input should be a valid string [type=string_type, input_value={...}, input_type=dict] ``` **Actual Correct Configuration:** By creating a knowledge base via the web UI and examining the actual parameters, the correct configuration should be: ```json "retrieval_model_dict": { "search_method": "semantic_search", "reranking_enable": true, "reranking_mode": null, // Should be null or a string "reranking_model": { // The actual rerank configuration field "reranking_provider_name": "langgenius/xinference/xinference", "reranking_model_name": "Qwen3-Reranker-4B" }, ... } ``` **Problem Analysis:** 1. **Documentation Error:** The documentation describes `reranking_mode` as an object, but the actual API expects it to be a string (or null). 2. **Field Confusion:** The actual rerank configuration should use the `reranking_model` field, not the configuration placed within `reranking_mode`. 3. **Inconsistent Field Names:** The field name in the response is `retrieval_model_dict`, while it should be `retrieval_model` in the request. **Suggested Fixes:** 1. **Update API Documentation:** Change the description of `reranking_mode` from "object" to "string | null". 2. **Add Correct Example:** Include a correct example of using the `reranking_model` field in the documentation: ```json "retrieval_model": { "search_method": "hybrid_search", "reranking_enable": true, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "<string>", "reranking_model_name": "<string>" }, ... } ``` 3. **Clarify Field Usage:** Explain the difference and correct usage between `reranking_mode` and `reranking_model`. **Environment Information:** - API Version: v1 - Request Endpoint: `POST /v1/datasets` - Documentation Location: [Datasets API - Create an Empty Knowledge Base](https://docs.dify.ai/developers/apis#tag/Datasets/operation/create-dataset) **Additional Information:** This issue prevents developers from successfully creating a knowledge base with rerank configuration as per the documentation, requiring additional debugging and reverse engineering to find the correct parameter format. --- This issue clearly identifies the problem, provides a comparison between the error and the correct format, and offers specific suggestions for fixes, which will help the development team quickly locate and resolve the documentation error. ### Suggested Changes **Suggested Fixes:** 1. **Update API Documentation:** Change the description of `reranking_mode` from "object" to "string | null". 2. **Add Correct Example:** Include a correct example of using the `reranking_model` field in the documentation: ```json "retrieval_model": { "search_method": "hybrid_search", "reranking_enable": true, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "<string>", "reranking_model_name": "<string>" }, ... } ``` **Corrected Valid Request Body Example:** ```json { "name": "Test Knowledge Base", "description": "For testing", "indexing_technique": "high_quality", "permission": "only_me", "provider": "vendor", "embedding_model": "dengcao/Qwen3-Embedding-8B:Q4_K_M", "embedding_model_provider": "langgenius/ollama/ollama", "retrieval_model": { "search_method": "semantic_search", "reranking_enable": true, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "langgenius/xinference/xinference", "reranking_model_name": "Qwen3-Reranker-4B" }, "top_k": 3, "score_threshold_enabled": false, "score_threshold": 0.5 } } ``` ``` ### Reason for Change API Documentation Error: Incorrect Description and cURL Example for the `reranking_mode` Parameter in the "Create an Empty Knowledge Base" Interface! When using the `/v1/datasets` API to create an empty knowledge base, it was discovered that the description of the `retrieval_model.reranking_mode` parameter in the official documentation does not match the actual required format. Specific page URL: https://docs.dify.ai/api-reference/datasets/create-an-empty-knowledge-base#body-retrieval-model-reranking-mode-one-of-0-reranking-provider-name **Reproduction Steps:** 1. Send a request following the cURL example in the [official documentation](https://docs.dify.ai/developers/apis#tag/Datasets/operation/create-dataset): ```json "retrieval_model": { "search_method": "hybrid_search", "reranking_enable": true, "reranking_mode": { "reranking_provider_name": "<string>", "reranking_model_name": "<string>" }, ... } ``` 2. Receive a 400 error: ``` 1 validation error for DatasetCreatePayload retrieval_model.reranking_mode Input should be a valid string [type=string_type, input_value={...}, input_type=dict] ``` **Actual Correct Configuration:** By creating a knowledge base via the web UI and examining the actual parameters, the correct configuration should be: ```json "retrieval_model_dict": { "search_method": "semantic_search", "reranking_enable": true, "reranking_mode": null, // Should be null or a string "reranking_model": { // The actual rerank configuration field "reranking_provider_name": "langgenius/xinference/xinference", "reranking_model_name": "Qwen3-Reranker-4B" }, ... } ``` **Problem Analysis:** 1. **Documentation Error:** The documentation describes `reranking_mode` as an object, but the actual API expects it to be a string (or null). 2. **Field Confusion:** The actual rerank configuration should use the `reranking_model` field, not the configuration placed within `reranking_mode`. 3. **Inconsistent Field Names:** The field name in the response is `retrieval_model_dict`, while it should be `retrieval_model` in the request. ### Code of Conduct - [x] I agree to follow Dify's documentation [contribution guidelines](https://github.com/langgenius/dify/blob/0277a37fcad5ad86aeb239485c27fffd5cd90043/CONTRIBUTING.md) - [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones. - [x] I confirm that I am using English to submit this report, otherwise it will be closed. - [x] 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：） - [x] Please do not modify this template :) and fill in all the required fields.
yindo added the documentation label 2026-02-16 05:19:48 -05:00
yindo closed this issue 2026-02-16 05:19:48 -05:00
yindo commented 2026-02-16 05:19:48 -05:00
Author
Owner
Copy Link
Copy Source

@dosubot[bot] commented on GitHub (Dec 30, 2025):

You're correct: the API documentation currently describes retrieval_model.reranking_mode as an object, but the backend expects it to be a string or null. The reranking configuration (provider and model name) should be placed in a separate retrieval_model.reranking_model object. Supplying an object for reranking_mode causes a 400 validation error, as the API only accepts a string or null for this field, and expects the reranking details in reranking_model instead. This is confirmed by the authoritative schema in the codebase and by user reports of the same issue.

A correct example payload looks like this:

"retrieval_model": {
  "search_method": "hybrid_search",
  "reranking_enable": true,
  "reranking_mode": null,
  "reranking_model": {
    "reranking_provider_name": "<string>",
    "reranking_model_name": "<string>"
  },
  "top_k": 3,
  "score_threshold_enabled": false,
  "score_threshold": 0.5
}

To fix the docs, update the type of reranking_mode to "string | null", move the reranking provider/model fields into a separate reranking_model object, and clarify the distinction between these fields. The backend and UI both expect this structure, and the current docs are out of sync with the implementation and will cause validation errors if followed as written.
See code reference

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

Open in Cursor Join Discord Share on X

@dosubot[bot] commented on GitHub (Dec 30, 2025): <!-- Answer --> You're correct: the API documentation currently describes `retrieval_model.reranking_mode` as an object, but the backend expects it to be a string or null. The reranking configuration (provider and model name) should be placed in a separate `retrieval_model.reranking_model` object. Supplying an object for `reranking_mode` causes a 400 validation error, as the API only accepts a string or null for this field, and expects the reranking details in `reranking_model` instead. This is confirmed by the authoritative schema in the codebase and by user reports of the same issue. A correct example payload looks like this: ```json "retrieval_model": { "search_method": "hybrid_search", "reranking_enable": true, "reranking_mode": null, "reranking_model": { "reranking_provider_name": "<string>", "reranking_model_name": "<string>" }, "top_k": 3, "score_threshold_enabled": false, "score_threshold": 0.5 } ``` To fix the docs, update the type of `reranking_mode` to "string | null", move the reranking provider/model fields into a separate `reranking_model` object, and clarify the distinction between these fields. The backend and UI both expect this structure, and the current docs are out of sync with the implementation and will cause validation errors if followed as written. [See code reference](https://github.com/langgenius/dify/blob/9007109a6bf97ddd1766e13313a36d16b6d11182/api/services/entities/knowledge_entities/knowledge_entities.py#L78-L107) <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/624fd3a2-21d5-40ff-ba5a-bf1fd7a3ff28?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/624fd3a2-21d5-40ff-ba5a-bf1fd7a3ff28?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/624fd3a2-21d5-40ff-ba5a-bf1fd7a3ff28?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/624fd3a2-21d5-40ff-ba5a-bf1fd7a3ff28?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/624fd3a2-21d5-40ff-ba5a-bf1fd7a3ff28?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/624fd3a2-21d5-40ff-ba5a-bf1fd7a3ff28?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/624fd3a2-21d5-40ff-ba5a-bf1fd7a3ff28?feedback_type=other)</sup> [![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=You%27re%20correct%3A%20the%20API%20documentation%20currently%20describes%20%60retrieval_model.reranking_mode%60%20as%20an%20object%2C%20but%20the%20backend%20expects%20it%20to%20be%20a%20string%20or%20null.%20The%20reranking%20configuration%20%28provider%20and%20model%20name%29%20should%20be%20placed%20in%20a%20separate%20%60retrieval_model.reranking_model%60%20object.%20Supplying%20an%20object%20for%20%60reranking_mode%60%20causes%20a%20400%20validation%20error%2C%20as%20the%20API%20only%20accepts%20a%20string%20or%20null%20for%20this%20field%2C%20and%20expects%20the%20reranking%20details%20in%20%60reranking_model%60%20instead.%20This%20is%20confirmed%20by%20the%20authoritative%20schema%20in%20the%20codebase%20and%20by%20user%20reports%20of%20the%20same%20issue.%0A%0AA%20correct%20example%20payload%20looks%20like%20this%3A%0A%0A%60%60%60json%0A%22retrieval_model%22%3A%20%7B%0A%20%20%22search_method%22%3A%20%22hybrid_search%22%2C%0A%20%20%22reranking_enable%22%3A%20true%2C%0A%20%20%22reranking_mode%22%3A%20null%2C%0A%20%20%22reranking_model%22%3A%20%7B%0A%20%20%20%20%22reranking_provider_name%22%3A%20%22%3Cstring%3E%22%2C%0A%20%20%20%20%22reranking_model_name%22%3A%20%22%3Cstring%3E%22%0A%20%20%7D%2C%0A%20%20%22top_k%22%3A%203%2C%0A%20%20%22score_threshold_enabled%22%3A%20false%2C%0A%20%20%22score_threshold%22%3A%200.5%0A%7D%0A%60%60%60%0A%0ATo%20fix%20the%20docs%2C%20update%20the%20type%20of%20%60reranking_mode%60%20to%20%22string%20%7C%20null%22%2C%20move%20the%20reranking%20provider/model%20fields%20into%20a%20separate%20%60reranking_model%60%20object%2C%20and%20clarify%20the%20distinction%20between%20these%20fields.%20The%20backend%20and%20UI%20both%20expect%20this%20structure%2C%20and%20the%20current%20docs%20are%20out%20of%20sync%20with%20the%20implementation%20and%20will%20cause%20validation%20errors%20if%20followed%20as%20written.%20%20%0A%5BSee%20code%20reference%5D%28https%3A//github.com/langgenius/dify/blob/9007109a6bf97ddd1766e13313a36d16b6d11182/api/services/entities/knowledge_entities/knowledge_entities.py%23L78-L107%29)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify-docs/issues/652)
yindo commented 2026-02-16 05:19:48 -05:00
Author
Owner
Copy Link
Copy Source

@RiskeyL commented on GitHub (Jan 8, 2026):

Hi @Guofu1149, this has been fixed in #657. Thanks!

@RiskeyL commented on GitHub (Jan 8, 2026): Hi @Guofu1149, this has been fixed in #657. Thanks!
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
documentation
documentation
enhancement
pull-request
Mirrored from GitHub Pull Request
 question
stale
No Label documentation
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langgenius/dify-docs#297
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?