update

.env.example

@@ -1,31 +0,0 @@
-# ============================
-# HuggingFace Configuration
-# ============================
-
-# Tên repository model trên HuggingFace (BẮT BUỘC - thay bằng repo của bạn)
-MODEL_NAME=DeeAteTee/gemma-300m-it-matching-vn
-# Token xác thực HuggingFace (chỉ cần nếu repo là PRIVATE)
-
-# ============================
-# Model Configuration
-# ============================
-
-# HuggingFace token để tải model private
-HF_TOKEN=your_hf_token_here
-
-# Google API Key cho Gemini / Google AI (Bắt buộc để trích xuất CV)
-GOOGLE_API_KEY=your_google_api_key_here
-
-# Cấu hình thiết bị chạy: "cpu" hoặc "cuda"
-DEVICE=cpu
-
-# Giới hạn độ dài tối đa input text (tính theo tokens)
-MAX_LENGTH=512
-
-# ============================
-# MiniLM Configuration
-# ============================
-
-# Model MiniLM cho behavior-based matching (public, khong can token)
-MODEL_NAME_MINILM=sentence-transformers/all-MiniLM-L6-v2
-MAX_LENGTH_MINILM=256

plan.txt

@@ -1,9 +0,0 @@
-Luồng Triển Khai Tự Động Hóa AI API (FastAPI -> Docker -> AWS)
-1. Xây dựng Service với FastAPI (Tải Model 1 Lần)
-Bắt đầu bằng việc tạo một ứng dụng FastAPI để làm "lớp vỏ giao tiếp" giúp các ứng dụng khác gửi văn bản và nhận lại vector nhúng. Trong tệp mã nguồn main.py, bạn tiến hành khởi tạo ứng dụng FastAPI và thiết lập đoạn code để tải mô hình trực tiếp từ Hugging Face. Điểm mấu chốt ở đây là phải cấu hình để tải mô hình duy nhất một lần dưới dạng biến toàn cục (global variable) ngay khi ứng dụng khởi động. Việc này đảm bảo mô hình nằm sẵn trong RAM, tránh việc phải tải lại từ đầu mỗi khi có request mới. Kế tiếp, bạn cần định nghĩa hai endpoint chính: một endpoint GET (Health Check) trả về trạng thái hoạt động để xác nhận API đang chạy , và một endpoint POST xử lý Embedding. Endpoint này sẽ nhận văn bản đầu vào, truyền qua mô hình đã được load sẵn để trích xuất vector, và trả toàn bộ kết quả về dưới dạng JSON. Trước khi sang bước sau, hãy chạy thử cục bộ bằng lệnh fastapi dev main.py để đảm bảo API hoạt động trơn tru trên port 8000.
-
-2. Đóng gói Hệ Thống với Docker
-Để ứng dụng có thể chạy ổn định trên mọi máy chủ mà không lo lỗi môi trường, hãy đóng gói tất cả vào một Docker container. Tạo một tệp requirements.txt chứa danh sách các thư viện Python đã sử dụng (như fastapi, torch, transformers). Tiếp theo, thiết lập tệp Dockerfile với các bước tuần tự: chọn base image là Python chính thức (ví dụ: python:3.10) , tạo thư mục làm việc /code , copy tệp requirements.txt vào container và thực thi lệnh cài đặt. Sau khi cài xong thư viện, copy toàn bộ mã nguồn của bạn vào thư mục /code , và thiết lập lệnh (Command) để tự động khởi chạy server uvicorn/fastapi mỗi khi container được bật. Hoàn thiện việc đóng gói bằng cách chạy lệnh docker build để tạo image. Cuối cùng, tạo một repository trên Docker Hub , đổi tên (tag) cho image local khớp với repository này , và thực thi docker push để đưa image lên kho lưu trữ đám mây, sẵn sàng cho việc triển khai.
-
-3. Triển khai Vận hành trên AWS ECS (Fargate)
-Khi image đã sẵn sàng trên Docker Hub, bước cuối là đưa nó lên môi trường Internet thông qua Amazon Elastic Container Service (ECS). Truy cập AWS, tạo một Task Definition mới sử dụng hạ tầng AWS Fargate. Fargate sẽ tự động hóa việc quản lý máy chủ vật lý cho bạn. Tại đây, bạn cần chỉ định đủ tài nguyên RAM và CPU cho container, vì mô hình 300 triệu tham số sẽ cần một không gian nhớ nhất định để load thành công. Dán URL của Docker image vào cấu hình và mở port tương ứng (ví dụ 80 hoặc 8000). Tiếp đó, tạo một Cluster dùng Fargate và khởi tạo một Service bên trong Cluster này để đảm bảo API của bạn được duy trì chạy liên tục 24/7. Một thao tác bắt buộc để API có thể nhận được request từ bên ngoài là cấu hình Security Groups: bạn phải thêm Inbound Rules cho phép lưu lượng truy cập mạng (ví dụ 0.0.0.0/0) đi vào đúng port mà ứng dụng đang mở. Hoàn thành luồng bằng cách lấy Public IP được cấp và gọi thử một API request để nghiệm thu hệ thống.

test_api.py

@@ -1,267 +0,0 @@
-"""Script test nhanh cho Embedding API"""
-from urllib.request import urlopen, Request
-from urllib.error import HTTPError
-import json
-
-BASE_URL = "http://localhost:8000"
-
-
-def test_health_check():
-    print("=" * 50)
-    print("TEST 1: Health Check (GET /health)")
-    print("=" * 50)
-    r = urlopen(f"{BASE_URL}/health")
-    data = json.loads(r.read())
-    print(f"  Status: {r.status}")
-    print(f"  Response: {data}")
-    assert data["status"] == "ok", "Health check failed!"
-    print("  => PASSED\n")
-
-
-def test_single_text():
-    print("=" * 50)
-    print("TEST 2: Single Text Embedding (POST /embed)")
-    print("=" * 50)
-    payload = {"text": "hello world"}
-    req = Request(
-        f"{BASE_URL}/embed",
-        data=json.dumps(payload).encode(),
-        headers={"Content-Type": "application/json"},
-    )
-    try:
-        r = urlopen(req)
-        data = json.loads(r.read())
-        print(f"  Status: {r.status}")
-        print(f"  Dimension: {data['dimension']}")
-        print(f"  Num texts: {data['num_texts']}")
-        print(f"  Vector (first 5 values): {data['embeddings'][0][:5]}")
-        assert data["num_texts"] == 1, "Expected 1 text"
-        assert data["dimension"] > 0, "Dimension should be > 0"
-        print("  => PASSED\n")
-    except HTTPError as e:
-        error_body = e.read().decode('utf-8', errors='replace')
-        print(f"  ERROR {e.code}: {error_body.encode('ascii', 'backslashreplace').decode('ascii')}\n")
-
-
-def test_batch_texts():
-    print("=" * 50)
-    print("TEST 3: Batch Texts Embedding (POST /embed)")
-    print("=" * 50)
-    payload = {"texts": ["Python developer", "Data analyst", "Machine learning engineer"]}
-    req = Request(
-        f"{BASE_URL}/embed",
-        data=json.dumps(payload).encode(),
-        headers={"Content-Type": "application/json"},
-    )
-    try:
-        r = urlopen(req)
-        data = json.loads(r.read())
-        print(f"  Status: {r.status}")
-        print(f"  Dimension: {data['dimension']}")
-        print(f"  Num texts: {data['num_texts']}")
-        print(f"  Num vectors: {len(data['embeddings'])}")
-        assert data["num_texts"] == 3, "Expected 3 texts"
-        assert len(data["embeddings"]) == 3, "Expected 3 vectors"
-        print("  => PASSED\n")
-    except HTTPError as e:
-        print(f"  ERROR {e.code}: {e.read().decode()}\n")
-
-
-def test_empty_input():
-    print("=" * 50)
-    print("TEST 4: Empty Input (POST /embed) - Should return 400")
-    print("=" * 50)
-    payload = {}
-    req = Request(
-        f"{BASE_URL}/embed",
-        data=json.dumps(payload).encode(),
-        headers={"Content-Type": "application/json"},
-    )
-    try:
-        r = urlopen(req)
-        print(f"  UNEXPECTED: Got status {r.status} (expected 400)\n")
-    except HTTPError as e:
-        body = json.loads(e.read().decode())
-        print(f"  Status: {e.code}")
-        detail_msg = body.get('detail', 'N/A')
-        print(f"  Detail: {detail_msg.encode('ascii', 'backslashreplace').decode('ascii')}")
-        if e.code == 400:
-            print("  => PASSED (correctly rejected empty input)\n")
-        else:
-            print(f"  => FAILED (expected 400, got {e.code})\n")
-
-
-def test_similarity_text():
-    print("=" * 50)
-    print("TEST 5: Text Similarity (POST /similarity)")
-    print("=" * 50)
-    payload = {
-        "text1": "Python developer with Django experience",
-        "text2": "Looking for Python programmer who knows Django framework"
-    }
-    req = Request(
-        f"{BASE_URL}/similarity",
-        data=json.dumps(payload).encode(),
-        headers={"Content-Type": "application/json"},
-    )
-    try:
-        r = urlopen(req)
-        data = json.loads(r.read())
-        print(f"  Status: {r.status}")
-        print(f"  Similarity score: {data['similarity_score']}")
-        print(f"  Percentage: {data['percentage']}%")
-        assert 0 <= data["similarity_score"] <= 1, "Score should be between 0 and 1"
-        assert data["percentage"] > 0, "Percentage should be > 0"
-        print("  => PASSED\n")
-    except HTTPError as e:
-        error_body = e.read().decode('utf-8', errors='replace')
-        print(f"  ERROR {e.code}: {error_body.encode('ascii', 'backslashreplace').decode('ascii')}\n")
-
-
-def test_similarity_vectors():
-    print("=" * 50)
-    print("TEST 6: Vector Similarity (POST /similarity/vectors)")
-    print("=" * 50)
-    # First, get 2 real vectors from /embed
-    texts = ["Software engineer", "Truck driver"]
-    req1 = Request(
-        f"{BASE_URL}/embed",
-        data=json.dumps({"texts": texts}).encode(),
-        headers={"Content-Type": "application/json"},
-    )
-    try:
-        r1 = urlopen(req1)
-        embed_data = json.loads(r1.read())
-        vec1 = embed_data["embeddings"][0]
-        vec2 = embed_data["embeddings"][1]
-
-        # Now compute similarity from vectors
-        payload = {"vector1": vec1, "vector2": vec2}
-        req2 = Request(
-            f"{BASE_URL}/similarity/vectors",
-            data=json.dumps(payload).encode(),
-            headers={"Content-Type": "application/json"},
-        )
-        r2 = urlopen(req2)
-        data = json.loads(r2.read())
-        print(f"  Status: {r2.status}")
-        print(f"  Texts compared: '{texts[0]}' vs '{texts[1]}'")
-        print(f"  Similarity score: {data['similarity_score']}")
-        print(f"  Percentage: {data['percentage']}%")
-        assert -1 <= data["similarity_score"] <= 1, "Score should be between -1 and 1"
-        print("  => PASSED\n")
-    except HTTPError as e:
-        error_body = e.read().decode('utf-8', errors='replace')
-        print(f"  ERROR {e.code}: {error_body.encode('ascii', 'backslashreplace').decode('ascii')}\n")
-
-
-def test_similarity_mismatched_vectors():
-    print("=" * 50)
-    print("TEST 7: Mismatched Vectors (POST /similarity/vectors) - Should return 400")
-    print("=" * 50)
-    payload = {
-        "vector1": [0.1, 0.2, 0.3],
-        "vector2": [0.1, 0.2],
-    }
-    req = Request(
-        f"{BASE_URL}/similarity/vectors",
-        data=json.dumps(payload).encode(),
-        headers={"Content-Type": "application/json"},
-    )
-    try:
-        r = urlopen(req)
-        print(f"  UNEXPECTED: Got status {r.status} (expected 400)\n")
-    except HTTPError as e:
-        print(f"  Status: {e.code}")
-        if e.code == 400:
-            print("  => PASSED (correctly rejected mismatched vectors)\n")
-        else:
-            print(f"  => FAILED (expected 400, got {e.code})\n")
-
-
-def test_minilm_single_text():
-    print("=" * 50)
-    print("TEST 8: MiniLM Single Text (POST /embed/minilm)")
-    print("=" * 50)
-    payload = {"text": "Python remote HCM"}
-    req = Request(
-        f"{BASE_URL}/embed/minilm",
-        data=json.dumps(payload).encode(),
-        headers={"Content-Type": "application/json"},
-    )
-    try:
-        r = urlopen(req)
-        data = json.loads(r.read())
-        print(f"  Status: {r.status}")
-        print(f"  Dimension: {data['dimension']}")
-        print(f"  Num texts: {data['num_texts']}")
-        assert data["dimension"] == 384, "MiniLM should return 384 dimensions"
-        print("  => PASSED\n")
-    except HTTPError as e:
-        error_body = e.read().decode('utf-8', errors='replace')
-        print(f"  ERROR {e.code}: {error_body.encode('ascii', 'backslashreplace').decode('ascii')}\n")
-
-
-def test_minilm_batch_texts():
-    print("=" * 50)
-    print("TEST 9: MiniLM Batch Texts (POST /embed/minilm)")
-    print("=" * 50)
-    payload = {"texts": ["Python remote HCM", "Product Manager", "BA"]}
-    req = Request(
-        f"{BASE_URL}/embed/minilm",
-        data=json.dumps(payload).encode(),
-        headers={"Content-Type": "application/json"},
-    )
-    try:
-        r = urlopen(req)
-        data = json.loads(r.read())
-        print(f"  Status: {r.status}")
-        print(f"  Dimension: {data['dimension']}")
-        print(f"  Num texts: {data['num_texts']}")
-        assert data["num_texts"] == 3, "Expected 3 texts"
-        assert data["dimension"] == 384, "MiniLM should return 384 dimensions"
-        print("  => PASSED\n")
-    except HTTPError as e:
-        error_body = e.read().decode('utf-8', errors='replace')
-        print(f"  ERROR {e.code}: {error_body.encode('ascii', 'backslashreplace').decode('ascii')}\n")
-
-
-def test_minilm_similarity_text():
-    print("=" * 50)
-    print("TEST 10: MiniLM Text Similarity (POST /similarity/minilm)")
-    print("=" * 50)
-    payload = {
-        "text1": "Python remote HCM",
-        "text2": "Looking for Python developer, remote working"
-    }
-    req = Request(
-        f"{BASE_URL}/similarity/minilm",
-        data=json.dumps(payload).encode(),
-        headers={"Content-Type": "application/json"},
-    )
-    try:
-        r = urlopen(req)
-        data = json.loads(r.read())
-        print(f"  Status: {r.status}")
-        print(f"  Similarity score: {data['similarity_score']}")
-        print(f"  Percentage: {data['percentage']}%")
-        assert 0 <= data["similarity_score"] <= 1, "Score should be between 0 and 1"
-        print("  => PASSED\n")
-    except HTTPError as e:
-        error_body = e.read().decode('utf-8', errors='replace')
-        print(f"  ERROR {e.code}: {error_body.encode('ascii', 'backslashreplace').decode('ascii')}\n")
-
-
-if __name__ == "__main__":
-    print("\n*** EMBEDDING API TEST SUITE ***\n")
-    test_health_check()
-    test_single_text()
-    test_batch_texts()
-    test_empty_input()
-    test_similarity_text()
-    test_similarity_vectors()
-    test_similarity_mismatched_vectors()
-    test_minilm_single_text()
-    test_minilm_batch_texts()
-    test_minilm_similarity_text()
-    print("*** ALL TESTS COMPLETE ***")