CodeFinder - Medical Code Search

FastAPI service tra cứu mã y tế (ICD10, ICPC2, CPT, SERVICE, PROCEDURE). Hybrid search: ChromaDB vector (all-MiniLM-L6-v2) + BM25. 3-tier cache. Port 8060.

Hoạt động

3-Tier Cache: L1 = LRU in-memory (2000 items), L2 = Redis (optional), L3 = MySQL persistent. Cache popular queries 7 ngày.

Base URL

https://pnt.badt.vn/codefinder

Authentication

Bearer token:

Authorization: Bearer <API_AI_TOKEN>

API Endpoints

POST /lookup Core

Tra cứu mã y tế. Hỗ trợ hybrid search (ChromaDB + BM25) với weight alpha.

Param	Type	Required	Description
text	string	Yes	Search query (1-500 ký tự)
code_type	string	No	ICD10, ICPC2, CPT, SERVICE, PROCEDURE, ALL (mặc định: ALL)
n_results	int	No	Số lượng kết quả (1-50, mặc định: 10)
use_cache	bool	No	Dùng cache (mặc định: true)
alpha	float	No	Hybrid weight: 1.0 = vector, 0.0 = BM25

POST /batch-lookup Batch

Tra cứu hàng loạt (tối đa 20 queries).

Param	Type	Required	Description
queries	array	Yes	List of lookup request objects (max 20)

GET /search Query

Tra cứu nhanh qua query params.

Param	Type	Required	Description
q	string	Yes	Search text
type	string	No	Code type (mặc định: ALL)
n	int	No	Results count

GET /code/{code_type}/{code} Direct

Tra cứu trực tiếp bằng mã code. Kiểm tra L1 cache → L2 Redis → database.

GET /health Utility

Health check: database, cache, search engine status.

Analytics

GET/analytics/top-queriesAnalytics

Top queries phổ biến. Params: limit, hours, code_type.

GET/analytics/slow-queriesAnalytics

Queries chậm. Params: threshold_ms, limit, hours.

GET/analytics/performanceAnalytics

Performance summary trong khoảng thời gian.

GET/analytics/cache-recommendationsAnalytics

Đề xuất cache dựa trên hit count.

Admin

POST/admin/invalidate-cacheAdmin

Xóa toàn bộ cache.

POST/admin/optimize-cacheAdmin

Warm cache với popular queries.

GET/admin/index-healthAdmin

Kiểm tra index status (ChromaDB + BM25).

POST/admin/rebuild-indexAdmin

Rebuild index cho code type cụ thể.

GET/admin/rebuild-status/{job_id}Admin

Kiểm tra trạng thái rebuild job.

GET/statsAdmin

Chi tiết cache + search engine stats.

Request Example

curl -X POST https://pnt.badt.vn/codefinder/lookup \
  -H "Authorization: Bearer $API_AI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "tăng huyết áp", "code_type": "ICD10", "n_results": 5}'

Response Example

{
  "results": [
    {"code": "I10", "description": "Essential (primary) hypertension", "score": 0.92},
    {"code": "I11.9", "description": "Hypertensive heart disease without heart failure", "score": 0.85}
  ],
  "query": "tăng huyết áp",
  "code_type": "ICD10",
  "response_time_ms": 45,
  "cache_hit": true
}

Thông số kỹ thuật

ServiceCodeFinder (FastAPI)

Port8060

Vector DBChromaDB (all-MiniLM-L6-v2)

KeywordBM25 (rank_bm25)

SearchHybrid (alpha-weighted)

Cache L1LRU in-memory 2000 items

Cache L2Redis (optional)

Cache L3MySQL persistent

DatabaseMySQL 192.168.1.244