Một tài liệu trở thành câu trả lời có trích dẫn như thế nào

§1Bài toán

§2Kiến trúc

• Phân lớp chặt: routes → controller → service → repository → db. Service không bao giờ import hono, nhờ vậy một job BullMQ gọi được đúng service mà HTTP route đang gọi.
• Frontend: Next.js 16 App Router, React 19, TanStack Query v5, ky + zod. Có Hono proxy nên URL backend không bao giờ lọt vào bundle.
• Không có lớp JWT. Backend xác thực trực tiếp session cookie của Better Auth; proxy chỉ chuyển tiếp, không thêm gì.
• Cookie workspace chỉ là lựa chọn của người dùng, không phải chứng thực. Nó được đối chiếu với danh sách membership thật, và backend trả 404 cho workspace bạn không thuộc về.
• Role ở client chỉ phục vụ UX (canContribute, canAdminister). Backend kiểm tra lại membership và role ở ranh giới tài nguyên trên mọi request.
• Text của chunk nằm ở Postgres; vector của nó nằm ở Qdrant, key theo id dòng chunk.

§3Pipeline, từng bước một

1. 01pending

   Ingest

   Payload cố tình mỏng. Job xếp hàng trước khi deploy sẽ chạy trên dữ liệu đúng ở thời điểm sau deploy, không phải trên một snapshot cũ.

   Hai lớp chặn dùng chung một id: enqueue trùng cùng attempt là no-op phía BullMQ, còn khoản trừ trong ledger cho attempt đó rơi vào đúng key ấy nên không thể ghi hai lần.

   Giới hạn ba lần là quyết định về chi phí: mỗi retry là một cuộc gọi provider mất tiền, và file hỏng không tự lành ở lần thứ tư.

2. 02parsing

   Parse

   Extractor tách theo hình dạng tài liệu chứ không chỉ theo đuôi file: general, structured, tabular, email và hierarchy, dựng trên unpdf, mammoth và exceljs.

   Mỗi section mang theo khoảng trang của nó, và chunk thừa hưởng thành fromPage và toPage.

   File không có lớp text dừng ở đây với lý do đọc được, thay vì thành một tài liệu rỗng được đánh dấu ready.

3. 03chunking

   Chunk

   Gộp chạy hai lượt: đoạn nào vượt ngân sách thì cắt tại dấu kết câu, rồi ghép các mảnh lại tới ngân sách token (mặc định 512), kèm phần trăm overlap lấy từ đuôi chunk trước.

   RAPTOR gom đoạn văn theo cosine similarity bằng một lượt greedy nearest-neighbour, cố ý không dùng UMAP+GMM. Dễ suy luận hơn, và việc gom nhóm trước khi model tóm tắt từng cụm không cần gì hơn thế.

   Chunk summary tồn tại để câu hỏi về cả tài liệu có thứ để khớp. Chúng được đánh dấu là do model viết, nên người đọc phân biệt được tóm tắt sinh ra với đoạn văn trích nguyên.

4. 04embedding → ready

   Embed

   Cỡ batch là giới hạn của provider, không phải nút tinh chỉnh, nên không ai đổi được nó qua cài đặt.

   Cắt input quá dài ở 8 000 token chỉ mất phần đuôi của một chunk; fail cả tài liệu thì mất tất cả.

   Cố định model theo knowledge base là lý do Qdrant có một collection cho mỗi model embedding, và là lý do hai base embed bằng model khác nhau không thể search chung về sau.

   Khả năng resume quan trọng nhất với PDF lớn: fail ở cuối chỉ embed lại những khoảng chưa trả tiền. Job bỏ cuộc thì dòng kết thúc ở failed, không phải ready.

5. 05

   Retrieve

   Hai điểm số nằm trên hai thang khác nhau, nên điểm lexical được chuẩn hoá theo kết quả tốt nhất trong tập trả về trước khi trộn. Cả hai phép search chạy trên cùng một corpus.

   Các base embed bằng model khác nhau bị từ chối kèm thông báo thay vì search chung, vì vector của chúng không so được với nhau.

   Màn hình tài liệu hiển thị chính các chunk, vì retrieval chỉ có thể trả về một trong những đoạn đó. Danh sách tài liệu chỉ poll khi còn dòng đang chạy và dừng ngay khi mọi dòng đã xong.

6. 06

   Cite

   Đoạn văn được lưu cùng message, không tra lại lúc render, nên thứ người đọc mở ra chính xác là thứ model đã thấy.

   Một agent run có thể search nhiều lần qua nhiều tool call. Đánh số một lần cho cả run thay vì mỗi lần search giữ [[1]] ổn định suốt câu trả lời.

§4Trình soạn agent flow

• Một graph DSL thuộc về sản phẩm, không thuộc về thư viện canvas. @xyflow/react chỉ là một view của nó; backend lưu và chạy nó, nên nâng cấp thư viện canvas không bao giờ là đổi định dạng dữ liệu.
• 16 loại node: begin, llm, knowledge_search, agent, categorize, switch, user_input, message, http, ocr, vision, stt, tts, excel, browser, loop.
• Node rẽ nhánh (categorize, switch) định tuyến qua params riêng của chúng. switch.otherwise tối đa 4 đích, loop tối đa 25 vòng, label tối đa 80 ký tự — tất cả mirror từ schema backend.
• validateFlow phía client mirror bộ quy tắc lúc publish của backend và bổ sung những lỗi backend chỉ phát hiện giữa run: prompt rỗng, nhánh nối vào khoảng không. Mỗi vấn đề mang blocksPublish tách khỏi level, nên bản đang dở vẫn lưu được trong khi một số lỗi nhất định vẫn hiện là error.
• Params tới client dưới dạng Record<string, unknown>. categoriesOf và casesOf kiểm tra có phải mảng không thay vì ép kiểu, vì đã có lần một chuỗi nằm ở chỗ đáng lẽ là danh sách làm sập cả màn hình agent.
• Run được checkpoint trên agent_run.state tại ranh giới node, chỉ lưu giá trị. Run chờ người dùng nhiều ngày vẫn sống qua deploy, và run bị crash được process khác tiếp tục.
• usage_ledger.reference = agent-run:{runId}:step:{seq} có unique index. Giữ nguyên seq qua các attempt chính là toàn bộ cơ chế chống trừ tiền hai lần.
• user_input tạm dừng run bao lâu cũng được. http từ chối các dải địa chỉ private.

§5Những quyết định khó

1. 01

   Trích dẫn được đóng băng phía server.

   Render là tra theo chỉ số, không bao giờ là khớp similarity có thể trôi sang sai đoạn. Vì sao không khớp lại lúc render: ít code hơn, nhưng similarity có thể rơi vào đoạn kế bên, và trích dẫn sai còn tệ hơn không có.

2. 02

   State streaming nằm ở local, không nằm trong query cache.

   Mỗi token một lần setQueryData thì mọi subscriber đều render lại. Stream ghi vào local state; cache được invalidate một lần lúc kết thúc và dữ liệu của server — kèm trích dẫn, model và chi phí — được lấy làm chuẩn.

3. 03

   Chỉ poll khi còn thứ đang chạy.

   Danh sách tài liệu dừng ngay khi mọi dòng đã ready hoặc failed. Vì sao không poll theo chu kỳ cố định: một trang đang đứng yên sẽ gọi API liên tục mà chẳng để làm gì.

4. 04

   Từ chối xảy ra trước khi stream mở.

   Hết credit, model ngoài gói, thiếu knowledge base: một 4xx bình thường kèm thông báo, không bao giờ là error frame sau khi UI đã chuyển sang trạng thái "đang trả lời".

5. 05

   Credit được cấp bởi webhook của Stripe, không bao giờ bởi lệnh checkout.

   Khoản cấp key theo id object của Stripe, nên event gửi lại rơi vào unique (kind, reference) của ledger và không làm gì cả. Vì sao không cấp lúc checkout: trình duyệt có thể đóng trước khi thanh toán hoàn tất, còn webhook thì có thể đến hai lần.

6. 06

   Khoá single-flight của auto-reload là một UPDATE có điều kiện.

   Không phải đọc-rồi-ghi, nên hai replica worker không thể cùng trừ tiền. Thẻ bị từ chối thì tắt auto-reload luôn thay vì retry mỗi năm phút.

7. 07

   Một credit = một input token của model baseline.

   Đơn giá của mỗi model suy ra từ chi phí provider và được đóng băng trên dòng usage cùng pricingVersion. Đổi giá không bao giờ viết lại lịch sử; dòng cũ vẫn nói đúng số tiền của ngày nó chạy.

§6Kết quả

§7Điều tôi sẽ làm khác

1. Đưa OCR vào đường ingestion. Hiện PDF scan fail với lý do rõ ràng, thế là trung thực, nhưng câu trả lời đúng là phải index được nó.
2. Giữ README backend đi cùng code. Nó vẫn ghi knowledge base, chat và agents là chưa làm, trong khi các module đã nằm trong src/modules.
3. Một HTTP client thay vì hai. Chat streaming và upload đi thẳng bằng fetch vì ky buffer response, để lại hai đường code phải thống nhất với nhau về auth và xử lý lỗi.