Neeze/lifemate-zac2026

LifeMate (Zalo AI Challenge 2026): ASR + SLM agent gọi tool

Lời nói tiếng Việt → PhoWhisper-large fine-tune → chuẩn hoá giờ (ITN) → Qwen3-4B-Instruct-2507 + LoRA v3-all (vLLM, greedy) → agent gọi tool qua zaic_tools (guard v1 + các bản sửa FIX) → submission.jsonl (id, tool_calls, state_hash).

Thành phần	Thư mục	Tham số
ASR: vinai/PhoWhisper-large fine-tune trên toàn bộ câu nói train (EXP1-all)	asr/phowhisper-large-ft/	1,55B
LLM: LoRA r16 trên Qwen/Qwen3-4B-Instruct-2507 (v3: ITN, 30% nhiễu ASR, che tên app 50%, 2 epoch, toàn bộ train)	llm/lora_v3all/	4,02B (+LoRA)
Tổng		5,57B < 6B, LLM < 5B, context 16.384

Model gốc Qwen3-4B tải từ Hugging Face (hoặc đặt --llm tới thư mục local khi chạy offline).

Kết quả đo

	Điểm
Dev 200 mẫu (adapter v3 train trên phần còn lại), vòng lặp gốc, 2 ví dụ few-shot	61,52
Cùng cấu hình, OpenAI Agents SDK Runner (--mode sdk)	60,93
Cùng cấu hình, OpenAI Agents SDK VoicePipeline (--mode voice)	60,60
Public test (adapter v3-all, vòng lặp gốc)	49,03

Thời gian (A100, chạy tuần tự từng mẫu): agent p50 1,4 s, max 5,7 s; ASR mỗi mẫu max 5,8 s → ước trên A30 xấu nhất ~20–23 s/mẫu. Mặc định có hạn chót 25 s cho phần agent: hết giờ thì dừng gọi LLM và nộp đúng các call đã thực thi.

Chạy

pip install -r requirements.txt
python run.py --root /data --split private_test --out result/submission.jsonl            # vòng lặp gốc (khuyên dùng)
python run.py --root /data --split private_test --out result/submission.jsonl --mode sdk # OpenAI Agents SDK Runner
python run.py --root /data --split private_test --out result/submission.jsonl --mode voice

--root phải có <split>/ và train/ (train.jsonl, train_tools_catalog.json, zaic_tools): train làm kho ví dụ few-shot (TF-IDF ký tự, 2 ví dụ gần nhất) và whitelist tham số tuỳ chọn. Gói này không kèm dữ liệu thi.

Agents SDK chỉ dùng model local qua vLLM (client OpenAI trỏ vào localhost), tắt tracing; không gọi dịch vụ ngoài.

Tuân thủ luật

• Không đọc file nào trong <split>_environment/; mọi đọc/ghi qua ToolEnv, đúng một ToolEnv mỗi mẫu (không replay để kiểm hash).
• Seed cố định, greedy (temperature 0). Chạy lại tuần tự so với bản 12 luồng: 8/634 chuỗi call khác.
• Chạy offline được khi đã có sẵn trọng số (đặt --llm tới thư mục local, HF_HUB_OFFLINE=1).

Cấu trúc

• run.py: CLI.
• lifemate_agent/core.py: lõi pipeline, sinh tự động từ notebook bản cuối (cấu hình, dữ liệu, ASR, vLLM, guard, agent).
• lifemate_agent/sdk_agent.py: vòng lặp OpenAI Agents SDK (Runner / VoicePipeline) + hạn chót mỗi mẫu.
• lifemate_agent/guard/: luật chuẩn hoá (số, giờ tiếng Việt) và guard.