Chuyển tới nội dung chính

AI Usage Logs (ai_usage_logs)

Mỗi bản ghi là nhật ký một lần gọi AI: dùng nhà cung cấp nào, tốn bao nhiêu token, có trúng cache không, có bị chặn bởi guardrail hay quota không. Phục vụ kiểm soát chi phí và gỡ lỗi.

  • Nguồn schema: ai-usage-log.schema.ts
  • Phân loại dữ liệu: gắn với userId nhưng không chứa nội dung hội thoại, chỉ số liệu kỹ thuật.
  • Soft-delete: plugin thêm isDeleted và deletedAt.

Data dictionary​

FieldTypeRequiredDefaultRàng buộcÝ nghĩa
userIdMixedCó—ref: UserNgười dùng thực hiện yêu cầu
conversationIdMixedKhông—ref: ConversationMã hội thoại ở cấu trúc cũ. Model đích không còn tồn tại
sessionIdMixedKhông—ref: ChatSessionPhiên chat phát sinh yêu cầu
operationTypeStringCó——Loại thao tác AI (chat, tóm tắt, phân loại...). Chuỗi tự do
providerStringKhông——Nhà cung cấp AI đã dùng
modelStringKhông——Tên mô hình đã dùng
intentStringKhông——Ý định người dùng được nhận diện
intentDetectionSourceStringKhông——Cách nhận diện ý định (luật hay mô hình)
promptTokensNumberKhông——Số token đầu vào do nhà cung cấp báo
completionTokensNumberKhông——Số token đầu ra do nhà cung cấp báo
totalTokensNumberKhông——Tổng token
estimatedPromptTokensNumberKhông——Số token đầu vào ước tính phía backend
latencyMsNumberKhông——Độ trễ của lần gọi, mili giây
estimatedCostUsdNumberKhông——Chi phí ước tính, USD. Bằng 0 nếu chưa cấu hình đơn giá
costEstimatedBooleanKhôngfalse—true khi số token đầu vào là ước tính của backend (nhà cung cấp không báo số thật)
cacheHitBooleanKhôngfalse—Phản hồi lấy từ cache, không gọi AI
cacheCategoryStringKhông——Nhóm cache được trúng
requestStartedAtDateKhông——Thời điểm bắt đầu xử lý
requestCompletedAtDateKhông——Thời điểm hoàn tất
successBooleanCó——Lần gọi thành công hay không
fallbackUsedBooleanKhôngfalse—Đã chuyển sang nhà cung cấp dự phòng
guardrailFlags[String]Không[]—Các cờ guardrail được kích hoạt
errorCategoryStringKhông——Nhóm lỗi nếu thất bại
quotaConsumedBooleanKhôngfalse—Lượt này đã tính vào quota
quotaRemainingNumberKhông——Quota còn lại sau lượt này
quotaResetAtDateKhông——Thời điểm quota được đặt lại
quotaUnavailableBooleanKhôngfalse—Không đọc được quota (ví dụ Redis lỗi)
quotaRollbackBooleanKhôngfalse—Quota đã được hoàn lại
topicGuardBlockedBooleanKhông——Bị chặn bởi bộ lọc chủ đề
topicGuardCategoryStringKhông——Nhóm chủ đề bị chặn
topicGuardLatencyMsNumberKhông——Độ trễ của bước lọc chủ đề, mili giây
createdAtDateKhông—immutableThời điểm tạo, do timestamps hoặc plugin
updatedAtDateKhông——Thời điểm sửa gần nhất, do timestamps
isDeletedBooleanCófalsethêm bởi plugin xóa mềmCờ xóa mềm. true nghĩa là bản ghi đã bị xóa khỏi nghiệp vụ nhưng vẫn còn trong database
deletedAtDateKhôngnullthêm bởi plugin xóa mềmThời điểm xóa mềm

Hầu hết các field có index: true ở mức field (16 index sau Phase 3a, đã xóa 5 index trùng tiền tố). Với collection ghi nhiều như nhật ký, số index lớn làm chậm ghi và tốn bộ nhớ. Chưa đo xem index nào thật sự được dùng. Trạng thái: Chưa xác minh.

Indexes​

KeysThuộc tínhMục đích
{ conversationId: 1 }—Index đơn lẻ trên field kế thừa
{ intent: 1 }—Index đơn lẻ từ index: true trên field
{ cacheCategory: 1 }—Index đơn lẻ từ index: true trên field
{ requestStartedAt: 1 }—Index đơn lẻ từ index: true trên field
{ requestCompletedAt: 1 }—Index đơn lẻ từ index: true trên field
{ success: 1 }—Index đơn lẻ từ index: true trên field
{ errorCategory: 1 }—Index đơn lẻ từ index: true trên field
{ quotaRollback: 1 }—Index đơn lẻ từ index: true trên field
{ topicGuardBlocked: 1 }—Index đơn lẻ từ index: true trên field
{ createdAt: -1 }—Xem nhật ký mới nhất
{ userId: 1, createdAt: -1 }—Nhật ký của một người dùng
{ sessionId: 1, createdAt: -1 }—Nhật ký của một phiên
{ provider: 1, success: 1, createdAt: -1 }—Thống kê tỉ lệ thành công theo nhà cung cấp
{ operationType: 1, createdAt: -1 }—Thống kê theo loại thao tác
{ cacheHit: 1, cacheCategory: 1, createdAt: -1 }—Thống kê tỉ lệ trúng cache
{ quotaConsumed: 1, quotaRollback: 1, createdAt: -1 }—Thống kê tiêu thụ và hoàn quota

Quan hệ​

FieldLoạiĐích
userIdReference, ref: 'User'users. Mixed, xem database-overview
sessionIdReference, ref: 'ChatSession'chat_sessions. Mixed
conversationIdReference, ref: 'Conversation'Model không tồn tại, field kế thừa từ cấu trúc cũ

Ví dụ document​

{
"_id": "665f1a2b3c4d5e6f7081a101",
"userId": "665f1a2b3c4d5e6f70819201",
"sessionId": "665f1a2b3c4d5e6f70819e01",
"operationType": "chat",
"provider": "groq",
"model": "example-model",
"intent": "job_search",
"promptTokens": 900,
"completionTokens": 250,
"totalTokens": 1150,
"latencyMs": 820,
"estimatedCostUsd": 0.0004,
"costEstimated": true,
"cacheHit": false,
"success": true,
"fallbackUsed": false,
"guardrailFlags": [],
"quotaConsumed": true,
"quotaRemaining": 29,
"topicGuardBlocked": false
}

Các giá trị operationType, model, intent, chi phí trong ví dụ là minh họa. Schema không giới hạn tập giá trị của operationType, provider, intent.

Lưu ý​

  • Known Limitation: không có TTL, bản ghi tăng vô hạn. Với tải chat lớn, đây là collection tăng nhanh nhất.
  • estimatedCostUsd được tính từ số token và đơn giá cấu hình, đọc lần lượt từ các biến AI_COST_<PROVIDER>_<MODEL>_<PROMPT|COMPLETION>_USD_PER_1K, AI_COST_<PROVIDER>_<PROMPT|COMPLETION>_USD_PER_1K, AI_COST_<PROMPT|COMPLETION>_USD_PER_1K (ai-usage.service.ts). Không đặt biến nào thì đơn giá là 0 và chi phí ghi là 0, nên con số 0 không có nghĩa là miễn phí. Mẫu ngắn nhất, ví dụ AI_COST_PROMPT_USD_PER_1K hoặc AI_COST_GROQ_COMPLETION_USD_PER_1K, đủ để bật tính chi phí.
  • costEstimated = true khi số token đầu vào là ước tính của backend vì nhà cung cấp không báo số thật; không liên quan tới việc đơn giá có được đặt hay không.
  • quotaRollback đánh dấu lượt chat bị hoàn quota (ví dụ lỗi nhà cung cấp), xem chat-quota-policies.