Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

[Feature] Add optional trace output to the RAG answer API for retrieval debugging

Aperta
  • Qualcosa non va?
#347 0 commenti 1 reazione 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@Nishieee ci sta già lavorando.

Dal 1/6/2026.

  • #354 di @Nishieee — aperta

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
48/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
python
Ambito
ai, api, backend-api-design

Direzione di ricerca

Iniziare da hugegraph-llm/src/hugegraph_llm/api/rag_api.py, nel TODO di /rag e nella risposta attuale, quindi confrontare il relativo flusso con /rag/graph e il modello RAGRequest. Verificare come vengono restituiti i dati di graph recall e i test proposti per API, contract, flow e sensitive-config. Il lavoro è completo quando la risposta predefinita rimane compatibile e include_trace=true restituisce un graph trace strutturato per le modalità graph specificate.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

enhancement
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

  • /rag has an explicit TODO saying more response information is needed for users to understand query logic in hugegraph-llm/src/hugegraph_llm/api/rag_api.py:79.
  • /rag currently returns only query and requested answer fields in hugegraph-llm/src/hugegraph_llm/api/rag_api.py:80.
  • /rag/graph already returns graph-recall intermediate fields including query, keywords, match_vids, graph_result_flag, gremlin, graph_result, and vertex_degree_list in hugegraph-llm/src/hugegraph_llm/api/rag_api.py:131.
  • RAGRequest does not currently define an include_trace or 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 /rag can include graph trace data without parsing logs.
  • Reuse existing /rag/graph field 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 /rag response 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

  • /rag without include_trace keeps the current response shape.
  • /rag with include_trace=true returns a structured trace object.
  • Trace includes graph recall fields when graph_only or graph_vector_answer is 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 /rag response 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
Lingua principale
Python
Stelle
144
Fork
91
Merge medio
7h 27m
PR unite (30g)
7

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di apache/hugegraph-ai

Tutte le issue di apache/hugegraph-ai

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.