From 58507dae5c04caea0dbce729e1387529d6fe2936 Mon Sep 17 00:00:00 2001 From: chengke <404835780@qq.com> Date: Thu, 8 Oct 2026 16:31:18 +0800 Subject: [PATCH] docs(retrieval): mark evidence_text as deprecated and always empty Keep evidence as the consume path and stop documenting evidence_text as a live projection. Co-authored-by: Cursor --- README.md | 4 ++-- docs/usage.md | 4 ++-- src/knowhere/types/retrieval.py | 4 ++-- tests/test_retrieval.py | 6 +++--- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 05cb3ef..c119c81 100644 --- a/README.md +++ b/README.md @@ -76,8 +76,8 @@ response = client.retrieval.query( print(response.router_used) print(response.answer_text) -print(response.evidence) # composed parts to consume -print(response.evidence_text) +print(response.evidence) # grouped [E n] parts to consume +print(response.evidence_text) # deprecated; always empty. Use evidence. print(response.stop_reason) print(response.failure_reason) diff --git a/docs/usage.md b/docs/usage.md index e8f7e00..f2a2444 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -541,8 +541,8 @@ response = client.retrieval.query( ) print(response.answer_text) # LLM-generated natural-language answer print(response.router_used) # "workflow_single_step", "small_kb_all", etc. -print(response.evidence) # composed parts to consume -print(response.evidence_text) # text projection of those parts +print(response.evidence) # grouped [E n] parts to consume +print(response.evidence_text) # deprecated; always empty. Use evidence. print(response.stop_reason) # agentic termination reason, when returned print(response.failure_reason) # no-answer reason, when returned for ref in response.referenced_chunks: diff --git a/src/knowhere/types/retrieval.py b/src/knowhere/types/retrieval.py index c67f60f..cbc3c70 100644 --- a/src/knowhere/types/retrieval.py +++ b/src/knowhere/types/retrieval.py @@ -79,8 +79,8 @@ class RetrievalQueryResponse(BaseModel): Downstream agents consume: - - ``evidence``: composed parts (text/HTML and inline images) - - ``evidence_text``: text projection of those parts + - ``evidence``: grouped ``[E n]`` parts (text/HTML and inline images) + - ``evidence_text``: deprecated; always empty. Use ``evidence``. - ``results``: raw path chunks for debug - ``decision_trace``: per-step navigation decisions (includes stop/failure) - ``referenced_chunks``: structured chunk citations for follow-up queries diff --git a/tests/test_retrieval.py b/tests/test_retrieval.py index 6fc1fb2..4037cf3 100644 --- a/tests/test_retrieval.py +++ b/tests/test_retrieval.py @@ -32,7 +32,7 @@ def _make_retrieval_response() -> Dict[str, Any]: "data": "abc", }, ], - "evidence_text": "Rendered retrieval evidence", + "evidence_text": "", "stop_reason": "answer_done", "failure_reason": "insufficient evidence", "decision_trace": [ @@ -157,7 +157,7 @@ def test_query_sends_request_and_returns_results(self, sync_client: Any) -> None assert response.results[0].source.section_path == "Policies / Billing / Refunds" assert response.answer_text == ("Annual plans may be refunded within 30 days of purchase.") assert len(response.referenced_chunks) == 1 - assert response.evidence_text == "Rendered retrieval evidence" + assert response.evidence_text == "" assert response.evidence[0].type == "text" assert response.evidence[0].text == "Annual plans may be refunded within 30 days." assert response.evidence[1].type == "image" @@ -344,7 +344,7 @@ def test_agentic_response_fields(self, sync_client: Any) -> None: assert response.referenced_chunks[0].file_path is None assert response.referenced_chunks[0].job_id == "job_123" assert response.referenced_chunks[0].asset_url == ("https://example.com/assets/chunk_001") - assert response.evidence_text == "Rendered retrieval evidence" + assert response.evidence_text == "" assert response.evidence[1].media_type == "image/png" assert not hasattr(response.results[0], "composed") assert response.stop_reason == "answer_done"