Sơ đồ chi tiết: docs/architecture_diagram.md, ARCHITECTURE.md.

Ba tầng tài liệu — đọc đúng phạm vi để tránh nhầm "đã có" với "mục tiêu":

Sự tồn tại của một file không đồng nghĩa capability đã hoàn thành — blueprint giữ scaffold persistence/, rag/, seat tools ở dạng chưa import vào runtime.

2.2. Lớp giọng nói (STT · SLM · TTS)

STT — Gipformer-65M-RNNT (docs/architecture/mvp-stt-gipformer.md):

• Kiến trúc Zipformer-RNNT (recurrent neural network transducer), chạy ONNX qua sherpa-onnx — không cần PyTorch/icefall khi suy luận.
• Mặc định FP32, CPU, 4 threads, modified_beam_search, 16 kHz, feature_dim=80; có tùy chọn INT8 để benchmark footprint (không mặc định coi INT8 = FP32 về chất lượng).
• AudioPreprocessor kiểm nội dung bằng ffprobe (không tin MIME/đuôi file), rồi ffmpeg tạo WAV PCM signed-16 mono 16 kHz. Contract: WAV/MP3/M4A/FLAC/OGG, ≤25 MB, ≤60 s; lỗi trả HTTP 413 (quá dung lượng) / 422 (format/duration/no-speech) / 503 (runtime chưa sẵn sàng). Transcript rỗng → no_speech, không gọi Qwen.
• GipformerSTT khóa concurrency ở mức một, chạy blocking inference trong worker thread. Kết quả kèm RTF (real-time factor) để đo tốc độ tương đối thời lượng.

SLM — Qwen3.5-4B Q4_K_M GGUF qua llama.cpp llama-server ở 127.0.0.1:8080 (docs/architecture/mvp-slm-agent.md; số xác minh trong pipeline.local.toml):

• temperature=0.0, seed=3407, non-thinking, max_tokens=256, context_size=8192 (lưu ý: doc mvp-slm-agent.md còn ghi 4096 — đã lỗi thời so với config; con số đúng theo code là 8192).
• Cưỡng chế xuất JSON hợp lệ khớp schema PlannerEnvelope (structured_output=json_schema của llama-server), nên output luôn parse được.
• Context mỗi turn chỉ gồm: system prompt tiếng Việt (apps/api/resources/prompts/slm_system_vi.txt) + transcript hiện tại + JSON Schema của decision và tool. Không gửi audio thô, trace cũ, hay kết quả turn trước — mỗi turn độc lập.

TTS — Piper VITS vi_VN-vais1000-medium qua sherpa-onnx (docs/architecture/mvp-tts.md) — nằm ngoài đường thực thi lệnh; mất tiếng không làm hỏng lệnh cabin:

• Chọn sherpa-onnx thay Piper native có lý do license: Piper hiện là GPL-3.0 (copyleft, rủi ro khi ship trong sản phẩm đóng), nhưng weights vẫn MIT và chạy qua sherpa-onnx (Apache-2.0) né được nghĩa vụ copyleft, đồng thời không phải ship thêm binary ARM64.
• render_response() (UI) và render_speech() (loa) sinh từ cùng template, chỉ khác lớp đại lượng: 24°C ↔ "hai mươi tư độ", 30% ↔ "ba mươi phần trăm" — bắt buộc vì espeak-ng không đọc đúng số/%/°C theo tiếng Việt.
• Dùng cache (sha256(text|model|speaker|speed) → WAV) thay vì thu âm sẵn; vivi tts-warm render trước 101 câu hay gặp.

Ghi chú: VAD hiện là whole_buffer (đệm nguyên câu), chưa phải VAD thật — chưa có endpointing streaming. Wake word "ORI" và tự ngắt khi im lặng chạy phía trình duyệt.

2.3. Ranh giới tin cậy (trust boundary)

Đây là điểm cốt lõi về an toàn: SLM bị coi là thành phần không đáng tin. Mọi đề xuất của nó phải qua tầng policy/ trước khi chạm vào trạng thái xe.

• Catalog đóng 8 tool (domain/tool_names.py): set_climate_power, control_climate_temperature, set_ceiling_light_power, control_ceiling_light_brightness, set_music_playback, control_music_volume, search_place, get_directions.
• Validate schema (policy/proposal_validator.py): parse JSON thô → kiểm Pydantic strict → ép về đúng tool trong allowlist (policy/tool_allowlist.py), kẹp tham số trong khoảng (nhiệt độ 16–30 °C, độ sáng/âm lượng 0–100 %), tối đa 4 lệnh mỗi lượt.
• Retry đúng một lần: validation_retries=1 — nếu validate hỏng, đính kèm chi tiết lỗi vào prompt và cho model thử lại một lần, không có lần hai; vẫn sai hoặc server lỗi → decision=error, zero tool call.
• 5 loại quyết định (domain/tool_calls.py: Decision): PROPOSED, CLARIFICATION, UNSUPPORTED, GREETING, ERROR. Tool ngoài allowlist, field thừa, range sai, hoặc non-proposed mà kèm tool call đều bị từ chối.

Ngữ nghĩa operation của 3 tool control_* (mvp-slm-agent.md §3.1) — ý nghĩa của value do operation quyết định, không suy từ độ lớn con số:

value=null ở nhánh tương đối để validator điền mặc định (1 °C · 10 % · 5 %).

Chống prompt injection cùng ranh giới (mvp-slm-agent.md §4): transcript chỉ là dữ liệu người dùng — nó không thể mở rộng allowlist hay đổi schema. Đây không phải sandbox bảo mật hoàn chỉnh, nhưng deterministic validation đảm bảo zero tool ngoài catalog. Các lệnh ngoài phạm vi (phanh, ga, vô lăng, cửa/khóa, ADAS) phải trả unsupported, không được map sang tool gần nhất.

Nguyên tắc bất biến: model chỉ sinh đề xuất, không phải hành động; chỉ tầng thực thi xác định (deterministic) mới đổi được trạng thái cabin. Với tìm đường, model không bao giờ sinh toạ độ — nó chỉ trích tên/place_id, còn toạ độ và origin do executor tự điền.

2.4. Tầng thực thi (executor)

• Ba nhóm cabin (điều hòa, đèn trần, nhạc) hiện chạy proposal-only: validate rồi trả executed=false, chưa đổi trạng thái phần cứng thật — đúng với giai đoạn nghiên cứu/mô phỏng.
• GeoapifyExecutor (tools/geoapify_executor.py) là executor thật đầu tiên của hệ thống. Config pipeline.local.toml đặt executor_backend = "geoapify". Nó gọi 3 endpoint Geoapify: autocomplete (tìm), place-details (lấy lat/lon), routing (tính lộ trình distance_m/duration_s).
• Xâu chuỗi tự động (Option A): khi cùng lượt có cả search_place và get_directions, executor phân giải điểm đến trước; nếu đúng một ứng viên thì tự nối sang tính đường; nếu nhiều ứng viên thì trả NEEDS_DISAMBIGUATION để hỏi lại tài xế.
• Có logic khử trùng lặp địa điểm (gom cụm theo cự ly + token tên, biên ~120 m) và tự chọn ứng viên trội (confident_pick) — chi tiết ở docs/research-category-va-khu-trung-lap-ket-qua-dia-diem.md.

Lưu ý trạng thái: phần backend tìm đường đã sẵn sàng. Ngoài ra history_turns = 0 — hội thoại nhiều lượt được ghi nhưng chưa ghép vào prompt (mỗi lượt xử lý độc lập). Đây là các khoảng cách cần đóng, không phải lỗi thiết kế.

2.5. Đánh giá & quan trắc

• Trace JSON lưu xuống đĩa cho từng lượt (data/artifacts/traces/YYYY-MM-DD/), có lifecycle running/completed và tồn tại qua restart. Mỗi attempt lưu: input, config/model path, prompt hash, response schema, raw output, validation error, HTTP metadata, latency, decision, tool proposal và executed=false.
• Latency tách nguồn client vs server (mvp-pipeline-tong-the.md §4): span browser (recording.capture, transport.upload, response.ui) đánh source=client; span API đánh source=server. Lưu ý bẫy cộng trùng: transport.upload là round-trip nên đã bao gồm thời gian xử lý server — UI hiển thị tách riêng, không cộng vào tổng server pipeline.
• Bộ chạy đánh giá dưới eval/: run_command_eval (độ chính xác lệnh), run_stt_eval (WER/CER + latency p50/p95 + RTF), run_tts_eval (round-trip WER/CER, TTFA, RTF), dataset eval/datasets/commands_vi.smoke.jsonl, tts_manifest.vi.jsonl.
• Có 33 file test dưới tests/ (unit, contract, integration): normalizer, cabin state, clarify loop, executor metrics, và nhiều test Geoapify (test_geoapify_dedup.py, test_geoapify_confident_pick.py, v.v.).

2.6. Thiết kế đề xuất — ba kiến trúc

Ở khâu thiết kế, nhóm cân nhắc ba kiến trúc pipeline. Kiến trúc A là kiến trúc đang chọn và đang chạy; B và C là hai hướng nghiên cứu để cải thiện độ chính xác với tên riêng/địa danh — chưa phải giải pháp đã chắc chắn, cần thực nghiệm mới kết luận.

Kiến trúc A — hiện tại (đã chọn). Một luồng STT duy nhất; nếu kết quả mơ hồ thì hỏi lại tài xế (human-in-loop), phản hồi của SLM đọc ra bằng TTS.

flowchart LR
    A[Audio] --> VAD --> STT --> SLM --> TOOL[Tool]
    TOOL --> TTS[TTS: phản hồi SLM]
    SLM -. kết quả mơ hồ .-> HITL[Hỏi lại tài xế]
    HITL -. TTS câu hỏi .-> A

Kiến trúc B — hai luồng STT nhẹ/nặng, cổng theo độ tự tin của SLM (nghiên cứu). Audio được đệm vào buffer trước, rồi mới đưa ra model STT. Chạy STT nhẹ trước; nếu độ tự tin của SLM thấp thì lấy lại audio từ buffer cho STT nặng chạy lại. Vẫn có human-in-loop ở cuối khi kết quả mơ hồ.

flowchart LR
    A[Audio] --> VAD --> BUF[Buffer âm thanh]
    BUF --> STTL[STT nhẹ] --> SLM1[SLM]
    SLM1 --> GATE{Độ tự tin SLM}
    GATE -->|đủ cao| TOOL[Tool]
    GATE -->|thấp| STTH[STT nặng]
    BUF --> STTH
    STTH --> SLM2[SLM] --> TOOL
    TOOL --> TTS[TTS]
    SLM1 -. mơ hồ .-> HITL[Hỏi lại tài xế]
    SLM2 -. mơ hồ .-> HITL

Đánh đổi (chưa kiểm chứng): chạy hai model STT tốn thêm bộ nhớ/độ trễ khi rơi vào nhánh nặng; ngưỡng cổng phải hiệu chỉnh để không kích hoạt oan.

Kiến trúc C — hai luồng STT (nhẹ + NER) song song (nghiên cứu). VAD xong, audio được đưa đồng thời vào STT nhẹ và một STT chuyên nhận dạng tên riêng/ địa danh (NER). "Trộn kết quả" nghĩa là thay cụm tên riêng do STT-NER phát hiện vào transcript của STT nhẹ, rồi mới đưa cho SLM. Vẫn có human-in-loop ở cuối.

flowchart LR
    A[Audio] --> VAD --> BUF[Buffer âm thanh]
    BUF --> STTL[STT nhẹ]
    BUF --> STTN[STT-NER: tên riêng/địa danh]
    STTL --> MERGE[Trộn: thay cụm tên riêng]
    STTN --> MERGE
    MERGE --> SLM --> TOOL[Tool] --> TTS[TTS]
    SLM -. mơ hồ .-> HITL[Hỏi lại tài xế]

Đánh đổi (chưa kiểm chứng): cần một STT-NER đủ tốt cho tiếng Việt và luật trộn đáng tin; nếu ranh giới cụm tên riêng sai thì trộn hỏng transcript. B và C cùng nhắm blocker tên địa danh tiếng Anh do người Việt nói (xem §3.3) nhưng bằng hai cơ chế khác nhau — sẽ so bằng thực nghiệm trước khi chọn.

3. Tính khả thi

3.1. Đã chạy được (đọc từ code + README §10)

• Chuẩn hóa audio (ffprobe/ffmpeg), kiểm định dạng và thời lượng.
• Nhận dạng tiếng Việt bằng Gipformer trên CPU.
• Sinh tool call bằng Qwen3.5-4B cục bộ, ép JSON schema, thử lại một lần.
• Sáu tool cabin có kiểm duyệt allowlist, áp lên trạng thái mô phỏng và phản hồi UI.
• Executor Geoapify thật cho tìm đường (backend), có khử trùng lặp + xâu chuỗi.
• Wake word "ORI", tự ngắt khi im lặng; TTS đọc phản hồi tiếng Việt.
• Khu kỹ sư với số liệu thời gian thực; trace JSON mỗi lượt.
• Đóng gói Docker multi-stage (web/api/slm), docker compose.

3.2. Điểm mạnh về khả thi

• Ưu tiên offline có căn cứ. Ba nhóm cabin không cần mạng; đây là tính năng cốt lõi và đã hoạt động ở mức mô phỏng.
• An toàn theo thiết kế. Model không thể trực tiếp đổi trạng thái xe; mọi lệnh qua schema + allowlist + kẹp khoảng. Đây là điểm phân biệt so với trợ lý LLM tự do.
• Có hạ tầng đo lường sẵn. Trace, eval runner và test giúp kiểm chứng được, phù hợp bản chất một dự án nghiên cứu.

3.3. Rủi ro & giới hạn (nêu thẳng)

• STT với tên địa danh tiếng Anh do người Việt nói là blocker đã biết cho nhóm tìm đường.
• Executor cabin vẫn proposal-only — chưa nối tới CAN/phần cứng thật, nên "đổi trạng thái cabin" hiện là mô phỏng.
• Tìm đường chưa gọi được từ model (system prompt còn từ chối) và geometry tuyến chưa render lên bản đồ UI.
• Chưa lưu bền (mất trạng thái khi khởi động lại; SQLite mới ở mức kế hoạch) và history_turns = 0 khiến đa lượt chưa thực sự dùng lịch sử.
• Ngoại lệ online cho tìm đường phá vỡ tuyên bố "offline hoàn toàn" — chỉ chấp nhận có chủ đích cho riêng domain này.

3.4. Về số liệu đánh giá

**Độ chính xác lệnh và WER của STT: chưa có số chính thức. Cần chạy và đo latency trên máy đích.

Ba metric chấm luồng gọi tool đã chốt (plan/ke-hoach-3-metric-goi-tool.md), định nghĩa lấy nguyên văn:

• Tool Accuracy — tỷ lệ mẫu dự đoán đúng tên công cụ; đa công cụ thì chuỗi dự đoán phải khớp đúng thứ tự (thứ tự là hợp đồng do prompt quy định: search_place rồi get_directions).
• Exact Match (EM) — tool và tất cả tham số khớp hoàn toàn nhãn tham chiếu sau chuẩn hoá xác định (giữ dấu thanh — bỏ dấu là mất thông tin phân biệt như Láng/Lãng).
• Slot F1 — mỗi tham số là một slot, tính Precision/Recall/F1 micro-averaged.

Hai cảnh báo đọc số bắt buộc kèm: (a) báo cả hai mẫu số @all (mọi lượt, đo cả năng lực biết khi nào không gọi tool) và @call (chỉ lượt phải gọi); (b) 22,2% slot là hằng số (ví dụ destination_place_id="pending", vehicle="car") đẩy Slot F1 lên "điểm không công" — nên phải in kèm Slot-F1@informative (bỏ 2 slot hằng).

Riêng TTS đã có số đo — nhưng đo trên máy dev x86, 2 thread, 22 câu, và chưa validate trên ARM64/AIBOX:

Hai caveat bắt buộc kèm số này: (a) mục tiêu TTFA < 150 ms chỉ đạt khi cache trúng — câu đơn không cache có TTFA ≈ thời gian tổng hợp cả câu (~300 ms); (b) round-trip WER đo độ dễ nghe tương đối với Gipformer, không phải MOS — một model có thể điểm cao mà vẫn nghe như robot, phải nghe tay trước khi chốt. 5/22 case lệch là do lỗi STT của Gipformer, không phải TTS.

Một cạm bẫy đo lường đã biết cho STT: WER công bố của Gipformer được chuẩn hóa bằng cách bỏ dấu thanh, nên không so trực tiếp với các mô hình báo cáo WER có dấu — benchmark phải báo cáo cả hai chế độ.

4. Hướng phát triển

4.1. Ngắn hạn — đóng khoảng cách đã biết

1. Bộ golden dataset cho tìm đường: chạy Geoapify thật trên các câu nav trước khi chốt nhãn (độ phủ dữ liệu tại POI cụ thể như chuỗi/ngõ chưa kiểm chứng). Tiếp tục làm giàu data.
2. Điền báo cáo đánh giá: chạy eval lệnh + STT, đo latency P50/P95 theo stage; chấm điểm phân giải điểm đến theo dung sai mét (đơn điểm ≤50 m, cổng ≤250 m) chứ không so toạ độ bằng ==.
3. Bật lịch sử đa lượt (history_turns > 0) và kiểm chứng bộ nhớ hội thoại.

4.2. Trung hạn — hoàn thiện MVP

• Executor cabin thật nối tới CAN bus / simulator trạng thái (thay proposal-only), có bước xác nhận (confirmation) cho lệnh nhạy cảm. Hiện tại đã có mô phỏng bằng MQTT
• Tầng NLU theo luật chạy trước SLM để giảm latency cho lệnh phổ biến.
• Lưu bền bằng SQLite cho trạng thái, lịch sử và số liệu.
• Đưa lên AI BOX 6490: build baseline CPU-only trên ARM64, đo latency/RAM/nhiệt độ/tải bền, rồi mới bật tăng tốc GPU/NPU sau khi xác minh stack BSP/driver/QAIRT.
• Đề xuất mô hình 2 STT (đính kèm 1 model STT name entity recognition) để sử dụng trường hợp code switching.

4.3. Dài hạn — triển khai biên

• RAG tra sổ tay xe (tùy chọn) — hiện POST /api/v1/manual/query trả no_evidence.
• Kiểm chứng offline thật: chạy toàn bộ luồng lõi khi ngắt mạng vật lý.
• Tính tuyến & chỉ đường rẽ từng bước (cần engine đồ thị đường cục bộ) — giai đoạn sau MVP.
• Bộ dữ liệu tiếng nói theo vùng miền (định hướng dài hạn): mở rộng golden dataset thành corpus có chủ đích cân đối theo vùng miền nói chung (Bắc/Trung/Nam), giới tính và độ tuổi, để đo và giảm chênh lệch độ chính xác STT giữa các giọng. Đây là tiền đề cho fine-tune/thích nghi miền về sau, không phải hạng mục MVP.

5. Công việc tuần tới

5.1. Thu âm & hoàn thiện golden dataset

Mục tiêu tuần tới là thu âm để biến bộ transcript chuẩn (đã có) thành golden dataset chấm được đầu-cuối bằng ba metric ở §3.4.

• Người nói: khoảng 9–15 giọng (số lượng còn dao động), chủ đích đa dạng vùng miền, giới tính, độ tuổi để bộ đo phản ánh phân bố người dùng thật.
• Hai môi trường thu:
  1. Phòng yên tĩnh — điều kiện gần lý tưởng, tách biến nhiễu.
  2. Trong xe — điều kiện vận hành thật (nhiễu động cơ, điều hoà, lốp/đường).
• Bridge set: một phần người thu-trong-xe thu lại chính họ trong phòng yên tĩnh, tạo cặp đối chứng cùng-người để đo mức suy giảm do nhiễu trong xe (tách ảnh hưởng môi trường khỏi ảnh hưởng giọng nói).
• Nghĩa vụ dữ liệu cá nhân: cần văn bản đồng ý (consent) của người thu và quy định lưu trữ/xoá rõ ràng trước khi thu — giọng nói là dữ liệu định danh.
• Chấm điểm: chạy harness đầy đủ, báo cáo Tool Accuracy / Exact Match / Slot F1 (kèm @all, @call, Slot-F1@informative như §3.4) và WER STT ở cả chế độ có dấu / bỏ dấu thanh.

5.2. Đưa lên thiết bị biên AI BOX 6490

Bước đưa hệ thống lên AI BOX 6490 nhằm đo trên phần cứng biên thật những chỉ số mà hạ tầng dev x86 / GPU đám mây (ví dụ T4) không mô phỏng được. Đây là phạm vi benchmark/mô phỏng nghiên cứu, không phải chuẩn xe hơi (automotive-grade) — thiết bị không sinh ra cho miền ô tô.

Thông số kỹ thuật AI BOX 6490 (xem Nguồn):

• SoC: Qualcomm® QCS6490.
• CPU Kryo™ 670 (big.LITTLE, 8 nhân): 1× Gold+ @ 2,7 GHz + 3× Gold @ 2,4 GHz
  • 4× Silver @ 1,9 GHz.
• GPU Adreno™ 643; VPU Adreno 633; DPU Adreno 1075; ISP Spectra™ 570L.
• DSP/NPU Hexagon™ (dual HVX, Hexagon Co-processor 2.0, Hexagon Tensor Accelerator): tới 12 TOPS, xử lý đồng thời 30–50 luồng AI.
• RAM 8 GB; lưu trữ eMMC 128 GB, hỗ trợ mở rộng SSD M.2 NVMe và thẻ Micro SD.
• Kết nối: Ethernet RJ45 1000 Mbps, 4× USB Type-A 3.0 + 1× USB Type-C, 4G/LTE CAT4 qua khe SIM nano (tùy chọn, kèm 2 đầu nối anten ngoài).
• Hệ điều hành: Android 13 hoặc Ubuntu 20.04.
• Điều kiện hoạt động: -25 °C đến +85 °C, độ ẩm 5–95% không ngưng tụ; nguồn vào 12 V qua jack barrel.

Vì sao phải đo trên thiết bị (số liệu không mô phỏng được ở nơi khác):

• Thông lượng INT8 trên NPU qua QNN/QAIRT: đường suy luận Hexagon INT8 chỉ tồn tại trên silicon này; GPU x86/T4 (FP16/INT8 khác vi kiến trúc) không cho con số đại diện.
• Sinh token bị chặn bởi băng thông bộ nhớ (RAM 8 GB LPDDR): tốc độ decode của SLM phụ thuộc băng thông LPDDR thực tế của AI BOX 6490, khác hoàn toàn GDDR/HBM trên GPU đám mây.
• Throttling nhiệt khi tản nhiệt thụ động: latency ổn định dưới tải bền chỉ đo được trên chính vỏ/tản của AIBOX, không suy ra từ máy dev có quạt.
• Ghim nhân big.LITTLE: ảnh hưởng của việc gán luồng vào A78 vs A55 lên latency llama.cpp / sherpa-onnx chỉ đo được trên đúng topo nhân này.

Trạng thái & phần việc còn lại: các bước SSH + kiểm cấu hình đã làm xong. Phần port còn lại:

1. Build ARM64 cho llama.cpp + sherpa-onnx (baseline CPU-only), đo latency/RAM/nhiệt/tải bền.
2. Và/hoặc chuyển sang NPU (QNN/QAIRT) sau khi baseline CPU đã có số đối chứng.

Nguồn (thông số AI BOX 6490 tra cứu ngoài repo)

• HSP Tek — AI BOX 6490, thông số kỹ thuật chi tiết (SoC, CPU, GPU, NPU, RAM, lưu trữ, kết nối, hệ điều hành, điều kiện hoạt động): https://hsptek.com/vi/san-pham/ai-box-6490/
• Qualcomm QCS6490 product brief (SoC nền tảng của AI BOX 6490): https://www.qualcomm.com/internet-of-things/products/q6-series/qcs6490

Phụ lục — nguồn tham chiếu trong repo