[inter-v2-03] Báo cáo deep-dive trace luồng OpenRouter embedding

[CodingMinh]

Fixes #410

Nội dung thực hiện

Báo cáo chi tiết được ghi nhận tại bench/INTER_V2_03_EMBEDDING.md, đáp ứng đầy đủ acceptance criteria của task [inter-v2-03]:

1. Giải thích luồng index → embed → upsert Qdrant:

   • Trace đầy đủ các giai đoạn: Document chunking (heading-chunks-2000-v1) -> tạo EmbeddingBatch job -> EmbeddingWorker claim với lease lock -> gọi ApprovedEmbeddingRuntime -> client-side $L_2$ normalize -> lưu vector vào Qdrant với lifecycle fencing và transaction an toàn.

2. Trace chi tiết 1 job embedding:

   • Trình bày mẫu HTTP request (POST /v1/embeddings), headers, JSON payload (model, input, dimensions: 1024).
   • Mẫu HTTP response trả về và quá trình chuẩn hóa $L_2$ client-side trước khi upsert vào Qdrant collection.

3. So sánh cấu hình môi trường:

   • Lập bảng so sánh chi tiết giữa mock POC (COMPOSE_PROFILES=mock, markhand-mock, 8-d) và OpenRouter thật (qwen/qwen3-embedding-8b, provider-cloud, 1024-d, normalize_client=true).

4. Lý do cần MARKHAND_ALLOW_CLOUD_EMBEDDINGS tường minh:

   • Phân tích sự khác biệt về threat model giữa LLM Q&A (chỉ gửi top-k trích dẫn) và Embedding indexing (gửi 100% full raw text chunks ra internet).
   • Giải thích cơ chế fail-closed guardrail bảo vệ dữ liệu khách hàng theo ADR 0005 và ADR 0016.

5. Danh sách biến môi trường bắt buộc:

   • Liệt kê và giải thích đầy đủ các biến môi trường cấu hình OpenRouter.

6. Phân tích Trade-off 1024-d vs 4096-d (từ benchmark DKP-02):

   • Đánh giá chỉ số Recall@5, nDCG gap, chi phí lưu trữ RAM/Disk (tiết kiệm 75%) và tốc độ tính toán ANN search trên Qdrant.

Cam kết

• Không commit secret / API key.
• Không thay đổi dimension hay model pin trong production index generation.