stt_and_intent_classifier

intent_classifier（意圖分類）與 stt_web（即時 STT + Web UI）的整合專案。

專案結構

stt_and_intent_classifier/
├── intent_classifier/   # 意圖資料、向量建置、Qdrant upsert、評測
└── stt_web/             # FastAPI + WebSocket + React 前端

系統流程（整合）

1. 在 intent_classifier 用 catalog 建 embeddings。
2. 將向量 upsert 到 Qdrant collection。
3. 啟動 stt_web/backend。
4. 前端把語音送到 /ws/audio，後端先做 STT，再呼叫 intent runtime 從 Qdrant 推論。

先決條件

• Python 3.10+
• Node.js 18+
• Docker（啟動 Qdrant）
• 可用的 Gemini API Key

1) 設定環境變數

intent_classifier/.env

GEMINI_API_KEY=your_key
# 可選
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=

stt_web/.env

# 向量 embedding / build script 會用到
GEMINI_API_KEY=your_key

# stt_web backend 的 gemini intent engine 會讀 GOOGLE_API_KEY
# 建議與 GEMINI_API_KEY 填同一把 key
GOOGLE_API_KEY=your_key

# 可選（預設值如下）
QDRANT_URL=http://localhost:6333
INTENT_COLLECTION=intent_l1
INTENT_INFER_ENGINE=vector
INTENT_EMBED_PROVIDER=gemini
INTENT_EMBED_MODEL=gemini-embedding-001
INTENT_GEMINI_MODEL=gemini-2.0-flash
INTENT_CLASSIFIER_ROOT=../intent_classifier

2) 啟動 Qdrant

在專案根目錄執行：

docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 \
  qdrant/qdrant

驗證：

curl http://localhost:6333/collections

3) 建置並上傳 Intent 向量

cd intent_classifier

python3 -m pip install --upgrade pip
python3 -m pip install pyyaml qdrant-client openai

# 用 20 類 catalog 建置（也可改成 data/intent_catalog_4class_v1.yaml）
python3 scripts/build_embeddings.py \
  --catalog data/intent_catalog.yaml \
  --provider gemini \
  --model gemini-embedding-001

python3 scripts/upsert_vectors.py \
  --collection intent_l1 \
  --vectors-jsonl artifacts/intent_vectors.jsonl \
  --centroids-jsonl artifacts/intent_centroids.jsonl

4) 啟動後端（stt_web/backend）

cd ../stt_web/backend

python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

python3 main.py

後端預設在 http://localhost:8000，主要介面：

• GET /health
• GET /api/models
• POST /api/analyze
• WS /ws/audio

5) 啟動前端（stt_web/web_app）

cd ../web_app
npm install
npm run dev

打開 http://localhost:5173。

前端預設連：

• API: http://localhost:8000
• WebSocket: ws://localhost:8000/ws/audio

6) 快速驗證

驗證 Intent runtime 已可用

curl -s http://localhost:8000/health

確認回傳裡的 intent_runtime.ready 為 true。

單句意圖測試

curl -s -X POST http://localhost:8000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"text":"我要查詢保單理賠進度"}'

常見問題

• intent_runtime.ready = false
  • 檢查 INTENT_CLASSIFIER_ROOT 是否正確指到 intent_classifier。
  • 確認 intent_classifier/configs/gate_config.yaml 與 scripts/stage1_infer.py 存在。
• Qdrant 連線錯誤
  • 檢查容器是否啟動、QDRANT_URL 是否正確。
• GEMINI_API_KEY is required
  • intent_classifier/.env 沒有正確設定，或 shell 沒有讀到 .env。
• 使用 intent_engine=gemini 時失敗
  • stt_web/.env 需要 GOOGLE_API_KEY（可與 GEMINI_API_KEY 同值）。

補充

• 預設推論引擎是 vector（低延遲，適合線上）。
• 可透過 session config 或 WebSocket 設定切換：
  • intent_collection（例如 intent_l1, intent_l1_4class_v1）
  • intent_engine（vector 或 gemini）
  • intent_interval_ms