Occupation Classification Mapping - Crosswalk

Mục lục

• Giới thiệu
• Mục tiêu
• Kiến trúc hệ thống
  • Pipeline và API Service
  • Deployment Architecture
• Cấu trúc dự án
• Cách sử dụng
  • Cài đặt
  • Docker Compose - Quick Start
  • Chạy Pipeline Local
  • Chạy API Service
  • Đồng bộ Milvus
• Service Accounts & Credentials
  • Tài khoản Test (Frontend Login)
• Pipeline Modular (src/pipeline/)
• Hiệu suất và so sánh
• Đóng góp
• Giấy phép

Giới thiệu

Dự án ánh xạ nghề nghiệp giữa các hệ thống phân loại:

• VSCO (Việt Nam Standard Classification of Occupations)
• ESCO (European Skills, Competences, Qualifications and Occupations)
• O*NET-SOC (Occupational Information Network)
• ISCO (International Standard Classification of Occupations)

Mục tiêu

• Xây dựng bộ ánh xạ (crosswalk) giữa VSCO và các tiêu chuẩn quốc tế ESCO, O*NET, ISCO
• 16 hướng ánh xạ (4 taxonomy × 4 taxonomy, gồm cả self-mapping)
• Áp dụng NLP và học sâu để tối ưu hóa quá trình ánh xạ
• API service với vector search (Milvus), graph database (Neo4j), full-text search (MongoDB)

Kiến trúc hệ thống

Pipeline và API Service

Kiến trúc tách biệt giữa Pipeline (local Python) và API Service (Docker):

Pipeline (Local Development)

• Mục đích: Xử lý dữ liệu, training model, tạo mappings, visualizations
• Môi trường: Host machine với Python virtual environment
• Quyền truy cập: Full read/write — data/, results/, models/, analysis_results/
• Entry points:
  • python -m src.pipeline.main (modular — khuyến nghị)
  • python run_complete_pipeline.py (legacy monolithic, 6,601 lines — frozen)

API Service (Production)

• Mục đích: Serve data qua REST API
• Môi trường: Docker containers, read-only mounts
• Components:
  • FastAPI backend (port 8001)
  • React frontend (port 3000)
  • PostgreSQL (5433), MongoDB (27017), Neo4j (7474/7687)
  • Milvus vector database (19530, 9091)
  • pgAdmin (5050), MLflow (5002 — profile)

Deployment Architecture

┌────────────────────────────────────────────────────────────┐
│                      HOST MACHINE                          │
│                                                             │
│  ┌───────────────────────────────────────┐                 │
│  │  Pipeline (Local Python)              │                 │
│  │  - python -m src.pipeline.main        │                 │
│  │  - Full R/W to data/ results/ models/ │                 │
│  └─────────────┬─────────────────────────┘                 │
│                │ Generates                                  │
│                ↓                                            │
│  ┌───────────────────────────────────────┐                 │
│  │  Shared Directories (read-only mounts)│                 │
│  │  - data/  results/  models/           │                 │
│  └─────────────┬─────────────────────────┘                 │
│                ↓                                            │
│  ┌───────────────────────────────────────┐                 │
│  │  Docker Containers                     │                 │
│  │  ┌──────────┐ ┌──────────┐ ┌────────┐ │                 │
│  │  │API:8001  │ │Frontend  │ │pgAdmin │ │                 │
│  │  │(FastAPI) │ │:3000     │ │:5050   │ │                 │
│  │  └──────────┘ └──────────┘ └────────┘ │                 │
│  │  ┌──────────┐ ┌──────────┐ ┌────────┐ │                 │
│  │  │PostgreSQL│ │MongoDB   │ │Neo4j   │ │                 │
│  │  │:5433     │ │:27017    │ │7474+   │ │                 │
│  │  └──────────┘ └──────────┘ └────────┘ │                 │
│  │  ┌──────────┐ ┌──────────┐            │                 │
│  │  │Milvus    │ │MLflow    │            │                 │
│  │  │19530+    │ │:5002     │            │                 │
│  │  └──────────┘ └──────────┘            │                 │
│  └───────────────────────────────────────┘                 │
└────────────────────────────────────────────────────────────┘

Cấu trúc dự án

project/
├── src/
│   ├── api/                      # FastAPI backend (33 route modules)
│   │   ├── routes/               # auth, pipeline, milvus, settings, ws, esco, onet, atlas...
│   │   ├── services/             # Model, embedder, graph, esco_api, onet_api, openai, atlas
│   │   ├── models/               # SQLAlchemy/MongoDB models
│   │   └── schemas/              # Pydantic schemas
│   ├── pipeline/                 # Modular pipeline (replaces legacy)
│   │   ├── main.py               # Orchestrator (~200 lines)
│   │   ├── cli.py                # Argparse with 50+ flags
│   │   ├── config.py             # All paths, models, mappings
│   │   ├── file_utils.py         # I/O helpers, env config, MLflow artifacts
│   │   ├── preprocessing/        # VSCO, ESCO, ONET processing + train/embed
│   │   ├── mapping/              # Dynamic mapper runner (16 directions)
│   │   └── visualization/        # Sankey, network graph, reports
│   ├── model/                    # 16 mapper modules + similarity calculators
│   └── frontend/                 # React 18 + MUI v7 SPA
├── data/                         # Pipeline I/O
│   ├── raw/ data_sources/ processed_data/
├── results/                      # Mapping output CSVs + stats
│   └── mappings/                 # Organized by model name
├── models/                       # Model files + embeddings
├── analysis_results/             # Figures, reports
├── scripts/                      # Utility scripts (data_processing, ml, tests)
├── docs/                         # Documentation
│   ├── reports/                  # Bug reports, audit, plan
│   ├── images/ references/
│   └── (01-09 categories)
├── docker-compose.yml            # All services
├── .env.example                  # Configuration template (copy to .env)
├── .env                          # Live secrets (gitignored)
├── run_complete_pipeline.py      # Legacy (frozen)
├── run_complete_pipeline_legacy.py # Original (reference only)
├── AGENTS.md                     # Agent instructions
└── README.md

Cách sử dụng

Cài đặt

# Clone và tạo .env
git clone <repo-url>
cp .env.example .env
# Chỉnh sửa .env với các API keys và secrets của bạn

# Python venv
python -m venv .venv
.venv\Scripts\Activate.ps1   # Windows PowerShell
pip install -r requirements.txt

# Frontend
cd src/frontend/occupation-mapping-app
npm install

Docker Compose - Quick Start

# Full stack
docker compose up -d

# Databases only (for local pipeline dev)
docker compose up postgres mongodb neo4j milvus -d

# With MLflow
docker compose --profile mlflow up -d

# View logs
docker compose logs -f api frontend

# Stop
docker compose down

Port Mapping:

Service	Port(s)	URL
API	8001	http://localhost:8001/docs
Frontend	3000	http://localhost:3000
PostgreSQL	5433 (host:container 5432)	psql via localhost:5433
MongoDB	27017	mongodb://localhost:27017
Neo4j	7474 (browser), 7687 (bolt)	http://localhost:7474
Milvus	19530 (gRPC), 9091 (metrics)
pgAdmin	5050	http://localhost:5050
MLflow	5002	http://localhost:5002

Chạy Pipeline Local (Modular)

Pipeline modular chạy trên host machine:

.venv\Scripts\Activate.ps1

# Tiền xử lý toàn bộ
python -m src.pipeline.main --preprocess

# Hoặc từng bước
python -m src.pipeline.main --process-vsco --process-esco --process-onet

# Train model metadata
python -m src.pipeline.main --train-model

# Tạo embeddings
python -m src.pipeline.main --create-embeddings

# Chạy mapping (tất cả 16 hướng)
python -m src.pipeline.main --run-mapping

# Chạy 1 hướng cụ thể
python -m src.pipeline.main --vsco-to-esco --isco-to-onet

# Với tham số nâng cao
python -m src.pipeline.main --run-mapping --threshold 0.75 --top-k 10 --improved-similarity --model-type multilingual_small

# Visualization
python -m src.pipeline.main --visualize-all

# Toàn bộ pipeline
python -m src.pipeline.main --preprocess --run-mapping --visualize-all --no-mlflow

Pipeline legacy (frozen, không khuyến nghị cho phát triển mới):

python run_complete_pipeline.py --preprocess --run-mapping --visualize-all

Chạy API Service (Production)

# Start full stack
docker compose up -d

# API auto-reads data from shared volumes
docker compose restart api   # sau khi pipeline chạy xong

Đồng bộ Milvus (sau khi pipeline chạy)

.venv\Scripts\Activate.ps1
python scripts/sync/sync_to_milvus.py

Benchmark hiệu suất Milvus vs Fallback

.venv\Scripts\Activate.ps1
python scripts/test/benchmark_milvus_vs_fallback.py

Service Accounts & Credentials

QUAN TRONG: Đây là credentials mặc định cho development. LUÔN thay đổi trước khi deploy production.

Service	Username	Password
PostgreSQL	postgres	occupation_mapping_pass
MongoDB	occupation_mapping	password
Neo4j	neo4j	password123
pgAdmin	admin@example.com	admin
API JWT	-	See JWT_SECRET_KEY in .env

Bảo mật JWT: Không sử dụng default key trong production. Thay đổi qua biến môi trường:

export JWT_SECRET_KEY="$(openssl rand -hex 32)"

Tài khoản Test (Frontend Login)

Tài khoản được tự động tạo khi API khởi động ở môi trường dev (ENVIRONMENT != production). Có thể đăng nhập tại http://localhost:3000/login:

Vai trò	Username	Password	Email
Quản trị	admin	Admin@2024Secure!	admin@example.com
Quản lý dữ liệu	datamanager	Manager@2024Secure!	datamanager@example.com
Người dùng	user	User@2024Secure!	user@example.com
Người dùng	testuser	Test@2024Secure!	test@example.com
Người dùng	vmtruong	TruongVo@2024Secure!	truongvo@foundamedia.com

Thay đổi mật khẩu (khuyến nghị trong production):

export SEED_ADMIN_PASSWORD="your_strong_password"
export SEED_MANAGER_PASSWORD="your_strong_password"
export SEED_USER_PASSWORD="your_strong_password"

Hoặc seed thủ công:

python src/api/seed_test_accounts.py

Trong production: Seed tự động bỏ qua khi ENVIRONMENT=production.

Pipeline Modular

16 hướng mapping

#	Direction	Module
1	VSCO → ESCO	vsco_to_esco_mapper_optimized
2	VSCO → O*NET	vsco_to_onet_mapper_optimized
3	VSCO → ISCO	vsco_to_isco_mapper_optimized
4	ESCO → VSCO	esco_to_vsco_mapper
5	ESCO → O*NET	esco_to_onet_mapper_optimized
6	ESCO → ISCO	esco_to_isco_mapper_optimized
7	O*NET → VSCO	onet_to_vsco_mapper_optimized
8	O*NET → ESCO	onet_to_esco_mapper_optimized
9	O*NET → ISCO	onet_to_isco_mapper_optimized
10	ISCO → VSCO	isco_to_vsco_mapper_optimized
11	ISCO → ESCO	isco_to_esco_mapper_optimized
12	ISCO → O*NET	isco_to_onet_mapper_optimized
13	VSCO → VSCO	Reuses cross-mapper (self-map)
14	ESCO → ESCO	Reuses cross-mapper (self-map)
15	ONET → ONET	Reuses cross-mapper (self-map)
16	ISCO → ISCO	isco_to_isco_mapper_optimized

CLI flags đầy đủ

# Individual mapping directions
--vsco-to-esco --vsco-to-onet --vsco-to-isco
--esco-to-vsco --esco-to-onet --esco-to-isco
--onet-to-vsco --onet-to-esco --onet-to-isco
--isco-to-vsco --isco-to-esco --isco-to-onet
--vsco-to-vsco --esco-to-esco --onet-to-onet --isco-to-isco

# Preprocessing nâng cao
--train-model --create-embeddings

# Visualization nâng cao
--sankey-output-dir DIR --sankey-all --sankey-type TYPE
--network-min-similarity FLOAT --network-max-edges INT
--network-all-types --network-multi-factor-ranking --auto-find

# Mapping nâng cao (v5.x)
--title-weight FLOAT --desc-weight FLOAT
--backend {torch,onnx,openvino}     # Execution backend
--truncate-dim INT                   # Matryoshka dimension truncation
--progressive-search                 # Coarse-to-fine Matryoshka search
--no-prompts                         # Disable encode_query/encode_document prompts
--reranker                           # Enable CrossEncoder reranking stage

# Training
--train                              # Fine-tune embedding model
--train-cross-encoder                # Fine-tune CrossEncoder reranker
--train-model MODEL                  # Base model for training
--train-epochs INT                   # Number of epochs
--train-batch-size INT               # Training batch size

v5.x Sentence-Transformers Features

Feature	Flag	Description
ONNX Backend	--backend onnx	ONNX Runtime inference (4-8x CPU speedup)
OpenVINO Backend	--backend openvino	Intel OpenVINO optimized inference
Matryoshka Truncation	--truncate-dim N	Use embeddings at N dimensions (e.g., 128)
Progressive Search	--progressive-search	Coarse filter at low dim, refine at high dim
Query/Doc Prompts	Enabled by default	Asymmetric encoding via encode_query/encode_document
CrossEncoder Reranker	--reranker	Two-stage: bi-encoder candidates → CE reranking
Hard-Negative Mining	Training default	mine_hard_negatives() for contrastive learning
CachedGISTEmbedLoss	Training default	Gradient caching + guided negatives
MatryoshkaLoss	Training default	Flexible-dimension embeddings

Điểm tương đồng (Similarity Scoring)

score = 0.3 * max(title_sim) + 0.15 * median(title_sim) + 0.55 * desc_sim
final = sigmoid(score)

Hiệu suất và so sánh

Phương pháp	Thời gian	Top-1	Top-3	Confidence
Cơ bản	~2 phút	78.24%	91.09%	0.718
EU Cải tiến	~3 phút	90.96%	95.45%	0.758

AI Search (tab=4) — Milvus vs Cũ

Chế độ	Engine	1 query	10 queries
AI Search (hiện tại)	Milvus	~0.037s	0.37s
AI Search (fallback)	NumPy vectorized	~10.36s	103.60s
Trước fix	Serial for-loop	102.42s	~1024s

Cải thiện: 2805x so với trước fix

Đóng góp

Xem AGENTS.md cho hướng dẫn phát triển, conventions, và các lỗi đã biết.

Giấy phép

MIT License — xem LICENSE để biết chi tiết.

O*NET Data Attribution: Sản phẩm này sử dụng dữ liệu từ O*NET Database, tạo bởi USDOL/ETA theo CC BY 4.0.

© 2023-2026 Laban.edu.vn.