duocthu/docs/current-rag-pipeline-audit.md

Audit pipeline RAG hội thoại hiện tại

Phạm vi: worktree D:\VSF-DUOCTHU ngày 2026-08-10. Báo cáo phản ánh implementation thật đang có trong worktree, bao gồm các thay đổi chưa commit. EXISTS không có nghĩa là đã đạt chất lượng production; nó chỉ nghĩa là đã tìm thấy implementation live tương đương.

1. Request path đã xác minh

ChatPanel.handleSendMessage
  -> POST /api/chat (Next.js BFF)
  -> POST /v1/rag/query (FastAPI)
  -> RagAgent.handle
       -> history + prior QueryFrame
       -> LlmQueryUnderstander.understand
       -> RagAgent._route
       -> RetrievalService.retrieve_framed / retrieve_by_indication
       -> Qdrant metadata route hoặc bounded fallback
       -> parent hydration + dedupe + evidence policy
       -> GroundedAnswerService.answer_from_result
       -> structured claim generation
       -> deterministic number/citation grounding
       -> semantic support + completeness verifier
  -> RagQueryResponse (answer blocks + claims + source ids)
  -> /api/chat mapping sang ChatMessage
  -> ChatBubble + CitationCard/Evidence panel

Đường live không dùng QueryRoutingService để fuzzy-resolve thuốc; class này còn được giữ cho retrieval-only fallback. Live agent dùng candidate-bounded LlmQueryUnderstander rồi truyền drug_id và section_key đã resolve vào RetrievalService.retrieve_framed.

Trace live đã chạy

Query	Kết quả	Latency quan sát	Đối chiếu raw
Levetiracetam cần tránh những điều kiện môi trường nào khi cất giữ? qua browser localhost:3000	answerable; block Bảo quản; 1 source, tr. 888	10,9 s end-to-end	Đủ 20–25 °C, tránh ánh sáng, dung dịch uống giữ trong bao bì ban đầu
Nêu đầy đủ tác dụng không mong muốn của Medroxyprogesteron acetat... qua API	answerable; 14 nhóm ADR	14,6 s	Tên ADR và điều kiện chính đủ; hierarchy tần suất kế thừa vẫn cần regression test chặt hơn
Bảo quản Levetiracetam thế nào?	abstain provider_unavailable	17,9 s	Không có answer để chấm; không tính pass
Medroxy completeness repair	abstain incomplete_answer	23,5–26,8 s	Cho thấy repair path có thể chạm budget/provider và làm latency xấu

Số mẫu trên chưa đủ để gọi là p50/p95. TTFB bằng gần toàn bộ latency vì response hiện là JSON nguyên khối, không có streaming.

2. Capability matrix

Capability	Status	Evidence implementation	Quyết định
Conversation state	PARTIAL	rag/agent.py:RagAgent._get_history/_remember; adapters/postgres.py:PostgresConversationStore	EXTEND: raw lines có window 6 turns; _last_frame chỉ in-process, không bền qua restart/multi-worker
Context resolution	PARTIAL	LlmQueryUnderstander.understand, _known_facts_block, _merge_with_prior_frame	EXTEND: merge có code backstop chủ yếu cho clarify continuation; topic switching vẫn phụ thuộc model
Standalone query rewrite	PARTIAL	rag/agent.py:_synthesize_query	EXTEND: đã fold population/age/weight/route/indication nhưng không lưu standalone_query first-class trong frame/trace
Active entity tracking	PARTIAL	QueryFrame.drugs; RagAgent._last_frame	EXTEND persistence/isolation; active frame hiện mất khi process restart
Intent/facet detection	EXISTS	QueryFrame.turn_type, attribute, population, route, indication; closed vocab trong understanding.py	REUSE; mở rộng multi-facet/reasoning mode, không thêm classifier call riêng
Metadata routing	EXISTS	RetrievalService.retrieve_framed; QdrantRetriever.find_by_section/find_by_drug	KEEP: known entity + facet đi thẳng đúng section
Dense retrieval	EXISTS	QdrantRetriever.search/search_indication	KEEP bounded fallback; không dùng cho mọi query
Sparse/lexical retrieval	PARTIAL	QdrantRetriever.search_lexical	EXTEND nếu cần: term-overlap/BM25-style, không phải một sparse vector/BM25 index đầy đủ
Hybrid/RRF	PARTIAL	rag/fusion.py:reciprocal_rank_fusion có testable primitive nhưng live RetrievalService chưa gọi	Không quảng cáo là live hybrid; chỉ wire sau eval chứng minh lợi ích
Reranker	PARTIAL	RetrievalService._rerank; BedrockCohereReranker trong bootstrap	KEEP: chỉ overview/similarity fallback; explicit section route cố ý không rerank
Parent/sibling expansion	PARTIAL	RetrievalService._hydrate parent hydration; _pooled_neighbour_hits bounded cross-section	KEEP bounded; không có generic sibling expansion cho mọi query
Evidence selector	PARTIAL	_hydrate dedupe, provenance/quarantine policy, pack_evidence token budget	EXTEND: chưa có explicit selected/rejected reason trace theo population/route relevance
Evidence sufficiency	PARTIAL	generation evidence_sufficient; _check_sufficiency; completeness verifier	EXTEND thành supported/partial/insufficient/conflicting; hiện boolean và fail toàn answer
Multi-section retrieval	PARTIAL	interaction gom evidence nhiều thuốc; than_trong opt-in lexical neighbor	EXTEND cho multi-facet có kế hoạch; không mở cross-section pooling toàn cục
Reasoning/multi-step logic	MISSING	Không có premise/conclusion representation hoặc bounded decomposition path	ADD sau P0–P2; không dùng agent loop cho simple lookup
Structured claims	EXISTS	prompt.py:ANSWER_SCHEMA; answer.py:_parse_claims	KEEP
Claim-to-evidence mapping	EXISTS	claim citation indices được map sang stable source_ids; response blocks giữ mapping	KEEP; bổ sung claim id/support status khi cần inference/partial
Grounding validation	EXISTS	grounding.verify; _verify_entailment	KEEP; completeness judge cần eval để giảm false positive/negative
Abstention	EXISTS	EvidenceDecision; granular reject reasons; provider/malformed/grounding guards	KEEP
Answer planning	PARTIAL	generation instruction + _answer_mode theo claim count + _build_blocks theo section	REPLACE heuristic bằng compact plan trong cùng generation call; không thêm LLM call
Adaptive verbosity	PARTIAL	_answer_mode chỉ dựa claim count; prompt phân biệt broad/specific	EXTEND theo query complexity/answer mode, không chỉ số claim
Response composition	PARTIAL	AnswerBlock/AnswerClaim và BFF DTO	EXTEND: hiện block granularity còn section-centric; chưa có lead/limitation/group hierarchy
SSE/streaming	MISSING	ChatPanel dùng await res.json(); FastAPI trả RagQueryResponse, không StreamingResponse	ADD sau correctness; hiện không được nói là streaming
Source rendering	EXISTS	CitationCard, evidence pane, printed/physical page, raw snippet	KEEP provenance; giảm chip lặp dưới từng claim
Semantic response components	PARTIAL	ChatBubble render AnswerBlock.kind; citation panel	EXTEND nhỏ; không biến mỗi paragraph/section thành card
Follow-up handling	PARTIAL	history, prior frame merge, latest-clarify quick replies, clarify circuit breaker	EXTEND và eval 50–100 turns; history window hiện 6 turns nên long chat chưa được chứng minh
Prometheus/Grafana	PARTIAL	/metrics, PrometheusMetrics, provisioned Grafana dashboard	KEEP aggregate counters; stack chưa được xác minh running trong audit này
Full request trace	PARTIAL	Postgres rag_retrieval_trace chỉ lưu query/decision/reason/resolved drug/citations	EXTEND stage timing/frame/route/evidence/guard verdict; không đưa lên user UI

3. Actual pipeline so với target

Phần nên giữ:

• candidate-bounded entity understanding;
• structured QueryFrame và deterministic metadata route;
• whole-section retrieval cho explicit facet;
• parent hydration, dedupe, provenance và quarantine;
• structured claims, deterministic numeric grounding và semantic verifier;
• Postgres conversation/trace, Prometheus counter và evidence panel.

Khoảng trống có tác động lớn nhất:

1. active frame không durable và standalone meaning không phải first-class output;
2. một attribute duy nhất không biểu diễn multi-facet query;
3. evidence selection/sufficiency chưa biểu diễn partial/conflicting;
4. chưa có direct/synthesis/inference mode và premise mapping;
5. answer plan chỉ là heuristic, renderer hiện quá card-heavy/source-heavy;
6. không streaming; latency 9–27 s và provider availability là lỗi backend thực;
7. trace chưa đủ stage timing để drill-down từ Grafana.

4. Failure taxonomy theo layer

Layer	Failure đã thấy hoặc có code path	Không được ngụy trang thành
Understanding/provider	timeout/throttle/malformed frame	user clarification
Context	stale entity, mất constraint, clarify loop	retrieval miss
Routing	sai facet, single-facet collapse	generator hallucination
Retrieval	wrong section, dense weak neighbor, parent missing	answer-style problem
Evidence	duplicate, mất heading/condition, token truncation	citation success
Generation	unsupported/partial/incomplete claim	“đã grounded”
Composition	hierarchy bị làm phẳng, source chip lặp	RAG correctness
Availability	provider unavailable, request budget exhausted	“không có trong Dược thư”
Observability	thiếu stage timing/selected-rejected evidence	user-facing technical trace

5. Smallest coherent change-set

Không dựng pipeline thứ hai. Mở rộng các abstraction đang có theo thứ tự:

1. P0 evidence/response contract: giữ structured claims, thêm answer plan nhỏ trong cùng generation call; hỗ trợ lead, semantic group và limitation; verifier trả support/completeness rõ, partial không bị trình bày như full.
2. P1 context: đưa standalone_query và depends_on_previous_turn vào QueryFrame; persist active frame cùng conversation store thay vì dict local.
3. P2 retrieval planning: cho frame mang nhiều facets; gọi retrieve_framed theo từng facet có giới hạn rồi dùng cùng decide/provenance policy. Không bật generic RRF/cross-section pooling nếu eval chưa chứng minh.
4. Composition/UI: prose/list là mặc định; warning/dosage/table chỉ khi plan yêu cầu; một affordance Xem căn cứ theo group/message, không chip dưới mọi dòng; bỏ dashboard chrome trong mỗi answer.
5. Trace/latency: stage timing và call counts vào internal trace/metrics; sau khi correctness ổn mới thiết kế safe streaming commit-by-verified-claim.

6. Những gì chưa được gọi là pass

• Batch 30 thuốc đã chạy xong nhưng không pass: chỉ 11/30 trả lời, 11/30 abstain và 8/30 hỏi lại. Đây là baseline trước bản sửa section_overview và evidence-quoted completeness bên dưới, không được dùng làm số sau-fix.
• Hội thoại dài đã chạy qua BFF; xem kết quả và giới hạn encoding ở mục 7.
• Prometheus/Grafana chưa được mở và xác minh trong phiên audit này.
• Không có p50/p95/p99 đủ mẫu.
• Grounded inference chưa được implement.
• Medroxy đã tốt hơn nhưng hierarchy tần suất cần test machine-checkable và browser review sau khi answer-plan contract hoàn thiện.

7. Kết quả triển khai và kiểm chứng ngày 2026-08-10

Thay đổi nhỏ trên đúng pipeline hiện hữu, không tạo pipeline thứ hai:

• QueryFrame có standalone_query, depends_on_previous_turn và section_overview. Tra toàn mục được tách khỏi yêu cầu chọn một liều cho ca bệnh; drug + facet rõ không còn bị classifier tự ý biến thành chip thu hẹp.
• Answer plan compact (verbosity, layout, reasoning_mode, heading/warning) được lập trước generation bằng code, không thêm model call.
• Completeness objection phải kèm evidence_quote; code kiểm tra quote tồn tại trong raw và thật sự hỗ trợ mô tả “bị thiếu”. Judge không còn có thể loại câu bảo quản chỉ vì câu hỏi nhắc “độ ẩm” trong khi raw không nêu độ ẩm.
• Renderer dùng prose/list mặc định, một Xem căn cứ cho group, không [1] [2] trong câu trả lời và không card cho từng claim.

Baseline random 30 trước-fix theo facet:

Facet	Answer	Abstain	Clarify	Nhận xét
Bảo quản	4	2	0	completeness false-positive
Tương tác	6	0	0	tốt nhất trong mẫu
ADR	1	5	0	incomplete/provider/grounding gây fail
Liều/cách dùng	0	2	4	ép population cho cả truy vấn toàn mục
Thận trọng	0	2	4	classifier hỏi lại dù facet đã rõ

Retest có đối chiếu raw:

• Levetiracetam sau-fix: answerable 9,3 giây; đủ 20–25 °C, tránh ánh sáng, dung dịch uống giữ bao bì ban đầu. Browser localhost sau hot path: 6,1 giây.
• Ergotamin tartrat: answerable 6,8 giây; giữ đúng nhiệt độ riêng theo dạng dùng.
• Isosorbid dinitrat toàn mục liều: answerable 19,9 giây thay vì chip; giữ nhãn chỉ định/đường dùng/liều, nhưng latency chưa đạt.
• Sildenafil ADR vẫn fail ungrounded_number; đây là fail đúng của safety gate, không được đổi nhãn thành pass.
• Ganciclovir, Glipizid, Vancomycin, Isradipin từng gặp provider_unavailable; availability/provider vẫn là blocker thực.

Validation code hiện tại:

• Ruff: pass.
• Pytest: 226 passed, 5 skipped.
• TypeScript --noEmit: pass.
• Next.js production build: pass.
• UI browser: pass về request/render; ảnh review xác nhận hết bullet kép và câu trả lời không còn citation marker nội tuyến.

Long conversation:

• Một conversation ID chạy 50 request liên tiếp qua localhost:3000/api/chat, không có HTTP error. Runner đầu làm mất dấu tiếng Việt trong user lines khi đi qua PowerShell nên không dùng 6 lượt cuối của lần này làm kết luận context.
• Giữ nguyên conversation đó và chạy sạch lượt 51–56 bằng chuỗi không lỗi encoding: Levetiracetam → follow-up chống chỉ định → đổi sang Isradipin → follow-up bảo quản → đổi sang Zolpidem → follow-up ADR. Cả ba follow-up đều bám đúng thuốc gần nhất; không rò Levetiracetam sang Isradipin/Zolpidem.
• Isradipin thận trọng ở lượt 53 bị incomplete_answer, nhưng lượt 54 vẫn resolve “thuốc này” đúng Isradipin và trả bảo quản dưới 30 °C, lọ kín, tránh sáng/ẩm.
• Latency lượt sạch 51–56: 6,9–18,8 giây; correctness context đạt trong kịch bản này nhưng tốc độ và provider/completeness availability chưa đạt.