[DOCS]: Error in API reference for "Retrieve Chunks from a Knowledge Base / Test Retrieval" #294

New Issue

2026-02-16T05:19:47-05:00

yindo commented

2026-02-16 05:19:47 -05:00

Originally created by @yangzq50 on GitHub (Dec 25, 2025).

Type of Documentation Change

Error/Typo fix

Documentation Page URL or Path

https://docs.dify.ai/api-reference/datasets/retrieve-chunks-from-a-knowledge-base-test-retrieval

Current Content

In the code block "Retrieve Chunks from a Knowledge Base / Test Retrieval", I see the following usage:

import requests

url = "https://api.dify.ai/v1/datasets/{dataset_id}/retrieve"

payload = {
    "query": "<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,
        "metadata_filtering_conditions": {
            "logical_operator": "and",
            "conditions": [
                {
                    "name": "<string>",
                    "comparison_operator": "<string>",
                    "value": "<string>"
                }
            ]
        }
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

The "reranking_mode" part is probably wrong.

The error also exists in:
https://github.com/langgenius/dify-docs/blob/47b663d99e710b22905c1971e20fbf9b1f36bdc9/en/api-reference/openapi_knowledge.json#L1772-L1784

Suggested Changes

I see another doc for 3.0.x, which can be used to access cloud.dify.ai service:
https://github.com/langgenius/dify-docs/blob/47b663d99e710b22905c1971e20fbf9b1f36bdc9/versions/3-0-x/en/user-guide/knowledge-base/knowledge-and-documents-maintenance/maintain-dataset-via-api.mdx?plain=1#L578-L602

Reason for Change

According to Dify source code, "reranking_mode" value can choose from "reranking_model" and "weighted_score".

https://github.com/langgenius/dify/blob/d01f2f7436eaa636b5cf5bfaf66bb0dbcb880e4d/api/core/rag/rerank/rerank_type.py#L1-L6

from enum import StrEnum


class RerankMode(StrEnum):
    RERANKING_MODEL = "reranking_model"
    WEIGHTED_SCORE = "weighted_score"

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 @yangzq50 on GitHub (Dec 25, 2025). ### Type of Documentation Change Error/Typo fix ### Documentation Page URL or Path https://docs.dify.ai/api-reference/datasets/retrieve-chunks-from-a-knowledge-base-test-retrieval ### Current Content In the code block "Retrieve Chunks from a Knowledge Base / Test Retrieval", I see the following usage: ```python import requests url = "https://api.dify.ai/v1/datasets/{dataset_id}/retrieve" payload = { "query": "<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, "metadata_filtering_conditions": { "logical_operator": "and", "conditions": [ { "name": "<string>", "comparison_operator": "<string>", "value": "<string>" } ] } } } headers = { "Authorization": "Bearer <token>", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` The "reranking_mode" part is probably wrong. The error also exists in: https://github.com/langgenius/dify-docs/blob/47b663d99e710b22905c1971e20fbf9b1f36bdc9/en/api-reference/openapi_knowledge.json#L1772-L1784 ### Suggested Changes I see another doc for 3.0.x, which can be used to access cloud.dify.ai service: https://github.com/langgenius/dify-docs/blob/47b663d99e710b22905c1971e20fbf9b1f36bdc9/versions/3-0-x/en/user-guide/knowledge-base/knowledge-and-documents-maintenance/maintain-dataset-via-api.mdx?plain=1#L578-L602 ### Reason for Change According to Dify source code, "reranking_mode" value can choose from "reranking_model" and "weighted_score". https://github.com/langgenius/dify/blob/d01f2f7436eaa636b5cf5bfaf66bb0dbcb880e4d/api/core/rag/rerank/rerank_type.py#L1-L6 ```python from enum import StrEnum class RerankMode(StrEnum): RERANKING_MODEL = "reranking_model" WEIGHTED_SCORE = "weighted_score" ``` ### 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 stale labels 2026-02-16 05:19:47 -05:00

yindo closed this issue

2026-02-16 05:19:47 -05:00

yindo commented

2026-02-16 05:19:47 -05:00

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

Hi @yangzq50! I'm Dosu and I’m helping the dify-docs team.

You're right—the documentation for the "reranking_mode" parameter is incorrect. The API expects "reranking_mode" to be a string with valid values "reranking_model" or "weighted_score", not an object with "reranking_provider_name" and "reranking_model_name" fields. The correct structure is supported by the codebase, where "reranking_mode" is defined as an enum with those two string options, and the reranking model details (provider and model name) are passed separately in a "reranking_model" object if needed (see code, retrieval logic).

The current docs and schema (for example, in openapi_knowledge.json) incorrectly show "reranking_mode" as an object. The correct usage is also reflected in the 3.0.x user guide, where "reranking_mode" is a string or null, and "reranking_model" is a separate object.

This error could cause confusion or failed API calls for users following the current example. The documentation and schema should be updated so "reranking_mode" is a string ("reranking_model" or "weighted_score"), and the reranking model details are provided in a separate "reranking_model" object if needed.

To reply, just mention @dosu.

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

@dosubot[bot] commented on GitHub (Dec 25, 2025):  Hi @yangzq50! I'm [Dosu](https://go.dosu.dev/dosubot) and I’m helping the dify-docs team.  You're right—the documentation for the "reranking_mode" parameter is incorrect. The API expects "reranking_mode" to be a string with valid values "reranking_model" or "weighted_score", not an object with "reranking_provider_name" and "reranking_model_name" fields. The correct structure is supported by the codebase, where "reranking_mode" is defined as an enum with those two string options, and the reranking model details (provider and model name) are passed separately in a "reranking_model" object if needed ([see code](https://github.com/langgenius/dify/blob/7e06225ce25ee354fab9f85bc85250bf0c5e89e2/api/core/rag/rerank/rerank_type.py#L4-L7), [retrieval logic](https://github.com/langgenius/dify/blob/7e06225ce25ee354fab9f85bc85250bf0c5e89e2/api/core/rag/data_post_processor/data_post_processor.py#L19-L99)). The current docs and schema (for example, in [openapi_knowledge.json](https://github.com/langgenius/dify-docs/blob/47b663d99e710b22905c1971e20fbf9b1f36bdc9/en/api-reference/openapi_knowledge.json#L1772-L1786)) incorrectly show "reranking_mode" as an object. The correct usage is also reflected in the [3.0.x user guide](https://github.com/langgenius/dify-docs/blob/47b663d99e710b22905c1971e20fbf9b1f36bdc9/versions/3-0-x/en/user-guide/knowledge-base/knowledge-and-documents-maintenance/maintain-dataset-via-api.mdx#L578-L602), where "reranking_mode" is a string or null, and "reranking_model" is a separate object. This error could cause confusion or failed API calls for users following the current example. The documentation and schema should be updated so "reranking_mode" is a string ("reranking_model" or "weighted_score"), and the reranking model details are provided in a separate "reranking_model" object if needed.  *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/498c7519-d805-4d4f-af0e-be8dfeee86b0?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/498c7519-d805-4d4f-af0e-be8dfeee86b0?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/498c7519-d805-4d4f-af0e-be8dfeee86b0?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/498c7519-d805-4d4f-af0e-be8dfeee86b0?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/498c7519-d805-4d4f-af0e-be8dfeee86b0?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/498c7519-d805-4d4f-af0e-be8dfeee86b0?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/498c7519-d805-4d4f-af0e-be8dfeee86b0?feedback_type=other)</sup> [![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=You%27re%20right%E2%80%94the%20documentation%20for%20the%20%22reranking_mode%22%20parameter%20is%20incorrect.%20The%20API%20expects%20%22reranking_mode%22%20to%20be%20a%20string%20with%20valid%20values%20%22reranking_model%22%20or%20%22weighted_score%22%2C%20not%20an%20object%20with%20%22reranking_provider_name%22%20and%20%22reranking_model_name%22%20fields.%20The%20correct%20structure%20is%20supported%20by%20the%20codebase%2C%20where%20%22reranking_mode%22%20is%20defined%20as%20an%20enum%20with%20those%20two%20string%20options%2C%20and%20the%20reranking%20model%20details%20%28provider%20and%20model%20name%29%20are%20passed%20separately%20in%20a%20%22reranking_model%22%20object%20if%20needed%20%28%5Bsee%20code%5D%28https%3A//github.com/langgenius/dify/blob/7e06225ce25ee354fab9f85bc85250bf0c5e89e2/api/core/rag/rerank/rerank_type.py%23L4-L7%29%2C%20%5Bretrieval%20logic%5D%28https%3A//github.com/langgenius/dify/blob/7e06225ce25ee354fab9f85bc85250bf0c5e89e2/api/core/rag/data_post_processor/data_post_processor.py%23L19-L99%29%29.%0A%0AThe%20current%20docs%20and%20schema%20%28for%20example%2C%20in%20%5Bopenapi_knowledge.json%5D%28https%3A//github.com/langgenius/dify-docs/blob/47b663d99e710b22905c1971e20fbf9b1f36bdc9/en/api-reference/openapi_knowledge.json%23L1772-L1786%29%29%20incorrectly%20show%20%22reranking_mode%22%20as%20an%20object.%20The%20correct%20usage%20is%20also%20reflected%20in%20the%20%5B3.0.x%20user%20guide%5D%28https%3A//github.com/langgenius/dify-docs/blob/47b663d99e710b22905c1971e20fbf9b1f36bdc9/versions/3-0-x/en/user-guide/knowledge-base/knowledge-and-documents-maintenance/maintain-dataset-via-api.mdx%23L578-L602%29%2C%20where%20%22reranking_mode%22%20is%20a%20string%20or%20null%2C%20and%20%22reranking_model%22%20is%20a%20separate%20object.%0A%0AThis%20error%20could%20cause%20confusion%20or%20failed%20API%20calls%20for%20users%20following%20the%20current%20example.%20The%20documentation%20and%20schema%20should%20be%20updated%20so%20%22reranking_mode%22%20is%20a%20string%20%28%22reranking_model%22%20or%20%22weighted_score%22%29%2C%20and%20the%20reranking%20model%20details%20are%20provided%20in%20a%20separate%20%22reranking_model%22%20object%20if%20needed.) [![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot) [![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/644)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: langgenius/dify-docs#294