AI trong hồ sơ độ khó Block Blast

Tài liệu thiết kế · 16/11/2026 · Backend Go + Firebase Remote Config

Trợ lý AI trong tab Hồ sơ độ khó hiện chỉ hiểu đúng khi admin gõ tên func. Bản thiết kế này sửa phần chọn func theo ngữ nghĩa bằng embedding (có keyword dự phòng), lưu vector bền trong Postgres, và chốt chi phí vận hành gần như bằng không.

Tóm tắt quyết định

Thay bước chọn 12 func ngẫu nhiên bằng xếp hạng tương đồng cosine (embedding chính, keyword dự phòng); catalog trong prompt giảm còn top 40 tên + 12 docs. Không fine-tune, không pgvector, không đổi frontend. Embed một lần cho 580 func, lưu bền trong Postgres, sau đó chỉ embed phần thay đổi.

00 Kiến trúc tổng thể: một lượt chat

Admin gửi câu hỏi (bấm tay) Backend Go DifficultyAI.Chat Embed API 1 call / tin nhắn Postgres 580 vector bền Cosine ranking (Go) fallback keyword nếu lỗi Prompt ~6k token top 40 tên + 12 docs + draft LLM API trả lờio + JSON đề xuất Validate whitelist Admin duyệt → Lưu → Publish nạp/thiếu → embed lô delta

Bảng chốt quyết định kỹ thuật

Quyết địnhLựa chọnLý do ngắn
Chọn func liên quanEmbedding cosine chính, keyword dự phòngCâu hỏi theo chủ đề không chứa tên func; keyword đảm bảo chạy được khi thiếu API
Lưu vectorPostgres bảng mới + cache RAM read-throughMất cache không re-embed; hash bắt docs đổi, chỉ embed delta
Catalog trong promptTop 40 tên + 12 docs; full 580 chỉ khi câu hỏi khám pháInput 10k → 6k token, giảm ~35% chi phí, vẫn giữ không gian đề xuất
Vector theo hồ sơ?Không — vector theo catalog funcGiá trị on/off/params là trạng thái đã có trong prompt, không đổi ngữ nghĩa
pgvectorKhông dùng580 vector tính cosine trong Go là micro giây; tránh dependency thừa
Fine-tune / train riêngKhôngThiếu data, catalog đổi thường xuyên, chi phí GPU vượt xa lợi ích
Model chốttext-embedding-3-small + gemini-3.5-flash-liteĐủ chất lượng tiếng Việt, ~$2.6/tháng cho 1.000 tin nhắn
FrontendKhông đổiAPI response giữ nguyên shape

01 Vấn đề hiện tại

Hàm pickDetailedFlags chọn tài liệu đưa vào prompt theo 3 tiêu chí: func đang xem, func có tên xuất hiện nguyên văn trong câu hỏi, func có override trong bản nháp. Hệ quả:

02 Giải pháp: hybrid relevance

Luôn đưa vào
Func đang xem, func nhắc tên, func có override
→
Slot còn trống
Xếp hạng theo ngữ nghĩa, lấp đến đủ 12 func
→
Embedding (chính)
Cosine similarity câu hỏi vs 580 func
→
Keyword (dự phòng)
Khi thiếu model embed hoặc API lỗi
→
Guardrail
Validate whitelist trước khi trả đề xuất cho admin

Văn bản embed của mỗi func ghép từ sẵn có: tên, nhóm, tags, tác dụng, thời điểm chạy. Bảng từ khóa tiếng Việt (bỏ dấu) ánh xạ sang category/tags: hồi sinh → revive, dễ hơn → easier, người mới → newbie, điểm → score.

AI chỉ đề xuất, admin duyệt rồi mới lưu và publish lên Firebase Remote Config. Không có đường tự động publish.

Catalog: top-N tên thay vì full 580

Thay vì gửi 580 tên cờ mỗi tin nhắn (~4-5k token), chỉ gửi tên top ~40 cờ theo relevance (~400 token) + docs đầy đủ 12 cờ đầu. AI vẫn có không gian đề xuất rộng gấp 3 lần phần docs, prompt input tụt từ ~10k xuống ~6k token. Full catalog chỉ gửi khi câu hỏi dạng khám phá ("liệt kê", "có những loại nào"). Nếu không có cờ phù hợp, AI nói rõ thay vì bịa tên.

03 Lưu trữ embedding

Vector lưu bền trong Postgres, bảng mới difficulty_flag_embeddings (flag_name, vector JSONB, model, text_hash, updated_at). Cache RAM chỉ là read-through:

Khởi động
Nạp toàn bộ vector từ Postgres vào RAM
→
So delta
Thiếu row, hash lệch (docs đổi), model lệch
→
Embed lô delta
1 API call batch, upsert bảng, cập nhật RAM
→
Mất cache
Nạp lại từ Postgres, không gọi embed API

Cosine similarity tính trong Go: 580 vector × ~1536 chiều là vài trăm nghìn phép nhân float, không đáng kể so với latency gọi LLM.

Số vector luôn bằng số func trong catalog, bất kể số lượng hồ sơ độ khó: vector thể hiện ý nghĩa của func (từ metadata), còn giá trị theo hồ sơ (on/off, params) đã được nhồi vào prompt mỗi lượt chat trong phần "HỒ SƠ ĐANG SỬA".

04 Chi phí embedding

ModelChiềuGiá / 1M tokenGhi chú
text-embedding-3-small Chọn1536$0.02Rẻ nhất, đủ tốt cho tiếng Việt
text-embedding-3-large3072$0.13Không cần cho 580 func
Cohere embed-multilingual-v3.01024$0.10Mạnh đa ngôn ngữ
Jina jina-embeddings-v31024$0.05Giá $0.02 trên site cũ đã lỗi thời
≈ $0.002
Embed 580 func một lần duy nhất
≈ $0.000001
Mỗi tin nhắn (embed câu hỏi)
+200–500ms
Latency mỗi tin nhắn, chấp nhận được cho thao tác bấm tay

05 Chi phí LLM chat (Gemini Flash)

Không tồn tại model tên gemini-3.5-flash; đây là các bản Flash hiện hữu (giá Standard, ưu đãi đến 31/12/2026, sau đó tăng gấp đôi):

ModelInput / 1MOutput / 1MGhi chú
gemini-3.5-flash-lite Chọn$0.30$2.50Đủ cho trả lờio ngắn + JSON đề xuất
gemini-3.8-flash$0.75$3.75Mạnh hơn, có Free tier
gemini-3.1-flash-lite$0.25$1.50Thế hệ trước

Ước tính per tin nhắn với gemini-3.5-flash-lite (input ~6k token: system ~300 + top 40 tên cờ ~400 + 12 docs ~4-5k + overrides; câu hỏi dạng khám phá gửi full catalog thì ~10k; output ~500 token): $0.0026/tin nhắn. Một nghìn tin nhắn mỗi tháng ≈ $2.6/tháng, và còn được miễn phí trong Free tier ở lượng vận hành admin. LLM chiếm trên 99% chi phí; embedding là phần bỏ đi.

06 Vì sao không fine-tune, không pgvector

Không fine-tune / train model riêng

Không pgvector

07 Kế hoạch triển khai

  1. Migration bảng difficulty_flag_embeddingsdb/migrations/0048_difficulty_flag_embeddings.sql
  2. Config env ROUTER_BRAIN_EMBED_MODELinternal/config/env.go · .env.example
  3. AIClient.Embed gọi endpoint embeddings chuẩn OpenAIinternal/service/aiclient.go + test
  4. Repo đọc/ghi vectorinternal/repo/difficultyProfiles.go + test
  5. Relevance ranking + load/upsert cache + keyword fallbackinternal/service/difficultyAI.go + test (TDD trước)
  6. Wiring handler, build và test toàn bộinternal/handler/difficultyprofiles.go · go build ./... && go test ./...

Kiểm chứng cuối: hỏi "làm game dễ hơn cho người mới" trên tab Hồ sơ độ khó → đề xuất phải thuộc nhóm easier/newbie thay vì func ngẫu nhiên.

08 Nguồn giá