Repository navigation
Labels
enhancementNew feature or requestNew feature or request
Description
Search before asking
- I had searched in the feature and found no similar feature requirement.
Feature Description (功能描述)
Feature Description
The /rag answer endpoint currently returns final answer fields only. For
retrieval debugging, users need an optional trace/debug response that includes
intermediate graph-recall information such as extracted keywords, matched vertex
IDs, generated Gremlin, graph recall results, and related graph debug fields.
The trace should be opt-in so the default response remains compact and backward
compatible. Vector recall and rerank traces can be handled as follow-up work
after the graph trace contract is stable.
Current verification
/raghas an explicit TODO saying more response information is needed for users to understand query logic inhugegraph-llm/src/hugegraph_llm/api/rag_api.py:79./ragcurrently returns onlyqueryand requested answer fields inhugegraph-llm/src/hugegraph_llm/api/rag_api.py:80./rag/graphalready returns graph-recall intermediate fields includingquery,keywords,match_vids,graph_result_flag,gremlin,graph_result, andvertex_degree_listinhugegraph-llm/src/hugegraph_llm/api/rag_api.py:131.RAGRequestdoes not currently define aninclude_traceor similar option.
Suggested scope
- Add an opt-in request field, for example
include_trace: bool = False. - Extend the graph-related RAG flow return contract or add a structured side channel so
/ragcan include graph trace data without parsing logs. - Reuse existing
/rag/graphfield names where possible. - Keep vector recall and rerank trace fields out of the required first version unless the implementation already exposes them cleanly.
- Avoid leaking secrets or full prompt contents by default.
- Keep the default
/ragresponse compatible for existing users.
Mermaid reference
flowchart LR
Request[/POST /rag include_trace/]
Request --> RAG[RAG answer flow]
RAG --> Answer[Answer fields]
RAG --> Trace{include_trace?}
Trace -->|false| Compact[Current response shape]
Trace -->|true| Debug[trace: keywords, match_vids, gremlin, graph_result]
Answer --> Compact
Answer --> Debug
Acceptance criteria
/ragwithoutinclude_tracekeeps the current response shape./ragwithinclude_trace=truereturns a structuredtraceobject.- Trace includes graph recall fields when
graph_onlyorgraph_vector_answeris used. - Vector recall and rerank trace fields are optional follow-up fields, not required for the first version.
- Missing unavailable trace sections are omitted or returned as empty structured values consistently.
Suggested tests
- API contract test for default
/ragresponse compatibility. - API test for
include_trace=true. - Flow-level test showing trace data is populated from graph recall.
- Test that sensitive config values are not included in trace.
Are you willing to submit a PR?
- Yes I am willing to submit a PR!
Code of Conduct
- I agree to follow this project's Code of Conduct
Reacted by dosubot
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity