86 lines
4.0 KiB
Markdown
86 lines
4.0 KiB
Markdown
# Kiến trúc và trạng thái hệ thống
|
|
|
|
> Loại chính: Explanation
|
|
> Đối tượng: developer, reviewer và operator
|
|
> Kiểm chứng: 2026-08-14
|
|
|
|
Hệ thống có hai luồng độc lập gặp nhau tại Qdrant: ingestion chạy offline để
|
|
biến PDF thành corpus; request path chạy online để hiểu câu hỏi, truy hồi bằng
|
|
chứng, tạo câu trả lời và kiểm tra grounding.
|
|
|
|
```text
|
|
Offline
|
|
PDF -> extract/repair -> monograph -> quarantine table/formula
|
|
-> chunk schema v4 -> embedding -> Qdrant + manifest
|
|
|
|
Online
|
|
Browser -> Next.js BFF -> FastAPI RAG
|
|
-> understand/guard -> Qdrant retrieval -> answer/validate
|
|
-> PostgreSQL trace + conversation + feedback
|
|
```
|
|
|
|
## Thành phần trên request path
|
|
|
|
1. `apps/web` cung cấp Next.js UI và BFF `/api/chat`.
|
|
2. BFF gọi `POST /v1/rag/query`, chuyển đổi DTO và map reason code cho UI.
|
|
3. `apps/ai-service` gắn correlation/trace context và điều phối RAG.
|
|
4. Qdrant giữ vector cùng payload provenance của chunk.
|
|
5. PostgreSQL giữ retrieval trace, conversation turn và feedback.
|
|
6. AWS Bedrock cung cấp query embedding; generation và rerank chỉ chạy khi bật.
|
|
|
|
Các service `api-gateway`, `auth-service`, `user-service` và `chat-service` là
|
|
scaffold, chưa nằm trên live request path hiện tại.
|
|
|
|
## Bản đồ repository
|
|
|
|
| Đường dẫn | Trách nhiệm |
|
|
|---|---|
|
|
| `apps/web` | UI và BFF Next.js |
|
|
| `apps/ai-service` | FastAPI, RAG orchestration, adapters, migrations, evals |
|
|
| `ingestion/ingestion` | PDF extraction, quality gates, chunking và load |
|
|
| `ingestion/data` | dữ liệu raw/processed và artifact |
|
|
| `packages/*` | shared types, API client và UI dùng chung |
|
|
| `infra/docker` | local Compose và observability |
|
|
| `infra/helm`, `infra/argocd` | target Kubernetes/GitOps |
|
|
| `.github/workflows` | CI, deploy, rollback và Qdrant migration |
|
|
| `docs` | bộ tài liệu chuẩn |
|
|
| `docs-legacy` | raw/legacy để tra lịch sử |
|
|
|
|
## Trạng thái triển khai
|
|
|
|
| Thành phần | Trạng thái được xác nhận |
|
|
|---|---|
|
|
| Web/BFF | có code, được lint và build trong CI |
|
|
| FastAPI RAG | có code và test tự động |
|
|
| PDF → chunk schema v4 | có code, quality gate và test |
|
|
| Qdrant manifest gate | runtime bắt buộc khi embedding bật |
|
|
| PostgreSQL trace/hội thoại/feedback | có migration và adapter |
|
|
| Bedrock Cohere embedding | production provider được runtime hỗ trợ |
|
|
| Answer generation | tùy chọn; mặc định tắt |
|
|
| Prometheus/Tempo/Grafana | có cấu hình local và production |
|
|
| EC2 Compose + Caddy | luồng deploy hiện hành trong GitHub Actions |
|
|
| Helm + ArgoCD | có manifest; chưa đủ bằng chứng để khẳng định đang phục vụ production |
|
|
| Frontend automated tests | chưa có test runner; CI chỉ lint/build |
|
|
| `visual-diff`, `scaffold-golden` | CLI tồn tại nhưng chưa triển khai |
|
|
|
|
## Mô hình triển khai
|
|
|
|
Local thường chạy PostgreSQL, Qdrant và observability bằng Compose; web và
|
|
ai-service chạy trực tiếp trên host. Các app service trong Compose local đang bị
|
|
comment nên `docker compose up` không tự tạo toàn bộ ứng dụng.
|
|
|
|
Production hiện hành được workflow mô tả là EC2 + Docker Compose + Caddy. CI và
|
|
deploy là hai workflow độc lập; operator phải chủ động áp gate CI xanh và xác nhận
|
|
SHA, health cùng synthetic query sau deploy.
|
|
|
|
Helm/ArgoCD là target platform có implementation trong Git. “Manifest render được”
|
|
không đồng nghĩa “cluster đang phục vụ traffic”; cần xác nhận cluster, secret,
|
|
image tag, ingress, health và rollback thực tế trước khi đổi trạng thái.
|
|
|
|
## Biên an toàn kiến trúc
|
|
|
|
Mỗi evidence phải có provenance về trang in và chunk. Generator không tự quyết
|
|
claim hợp lệ: code kiểm tra citation, số liệu, entailment và completeness. Khi
|
|
không chứng minh được, hệ thống trả `clarify`, `verify_pdf` hoặc `abstain`.
|
|
|