Skip to content

快速開始

English | 繁體中文

建立本機環境，並透過正式管道處理逐字稿。

先決條件

  • 支援 venv 的 Python 3（建議 3.12+，以符合目前依賴）
  • 可存取 OpenAI 相容 的聊天與嵌入端點
  • 字幕輸入（成對的 .srt + .mp3）與有效的主清單（{ "files": [ { "id", "path_srt", "path_mp3", … } ] }）
  • 足夠磁碟空間，供你設定的輸出路徑與 LanceDB 使用

安裝

git clone https://github.com/samson910022/TranscriptFlow.git
cd TranscriptFlow

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
cp scripts/config.example.json config.json

編輯 .env 與 config.json，設定 API 端點、API 金鑰、模型名稱、輸出目錄與 LanceDB 路徑。

機密資訊

切勿提交真實 API 金鑰、.env、config.json、產出檔或 LanceDB 資料。範例檔只能保留佔位符（例如 replace-with-your-api-key）。

主清單（初始化前必備）

管道預期主 JSON 物件具有頂層 files 陣列。每一列至少需要：

id、path_srt、path_mp3、filename_srt、filename_mp3

範例清單不能直接當正式輸入

examples/master_file_manifest.example.json 只是示意草稿。它可能是裸陣列，並使用 init_batch 不接受的舊欄位名（file_id、file_path）。不要把 SRT_MASTER_FILE 指過去就期望能成功跑，必須先改成正確形狀。

從成對 .srt / .mp3 的資料目錄產生有效清單：

# 只預覽配對、不寫檔
python3 scripts/generate_manifest.py --data-dir ./path/to/srt_mp3 --dry-run

# 寫出 master_file_manifest.json（路徑預設可來自 config 的 paths.data_dir / paths.master_file）
python3 scripts/generate_manifest.py --data-dir ./path/to/srt_mp3 --output ./examples/master_file_manifest.json
export SRT_MASTER_FILE="$PWD/examples/master_file_manifest.json"

generate_manifest.py 會指派與 files[] 索引相同的連續 id（0, 1, 2, …）。初始化預檢時，若 SRT 或 MP3 路徑任一在磁碟上不存在，該列會被標成 failed_permanent。

管線實際讀取的清單形狀：

{
  "files": [
    {
      "id": 0,
      "path_srt": "./data/example.srt",
      "path_mp3": "./data/example.mp3",
      "filename_srt": "example.srt",
      "filename_mp3": "example.mp3"
    }
  ]
}

載入環境變數

建議使用下列寫法，讓 .env 中類似 JSON 的值保留引號：

set -a && source .env && set +a

Note

請使用 set -a && source .env && set +a，不要用 export $(grep -v '^#' .env | xargs)。xargs 寫法可能會剝掉 JSON 值中的雙引號。

正式執行（看門狗）

依主清單初始化批次範圍，再讓看門狗推進各階段：

set -a && source .env && set +a

python3 scripts/state_manager.py init_batch 0 0
python3 scripts/auto_watchdog.py

init_batch START END 接受的是 manifest.files 的含頭含尾陣列索引，不是任意 file_id 值。上例只初始化索引 0（第一列）。被選中的每一列，其 id 欄位會成為管道的 file_id（供 --id 與狀態列使用）；若清單由 generate_manifest.py 產生，id 通常等於該索引。

較大批次前，請先把 SRT_MASTER_FILE、SRT_OUTPUT_DIR、SRT_DB_PATH（或對應的 paths.* 設定）指到你的資料。

看門狗會掃描批次狀態檔、啟動可執行階段、遵守階段並發限制，並重設超過設定工作時間上限的任務。

手動階段指令

除錯或對單一檔案做端到端即時驗證時，可對臨時輸出目錄明確執行各階段：

set -a && source .env && set +a
export SRT_OUTPUT_DIR="$PWD/output/live_validation"
export SRT_DB_PATH="$PWD/output/live_validation_db"

python3 scripts/state_manager.py init_batch 1 2
python3 scripts/summarize.py --id 1 --batch "$SRT_OUTPUT_DIR/batch_status_1_2.json" --phase chunking
python3 scripts/summarize.py --id 1 --batch "$SRT_OUTPUT_DIR/batch_status_1_2.json" --phase summarizing
python3 scripts/summarize.py --id 1 --batch "$SRT_OUTPUT_DIR/batch_status_1_2.json" --phase embedding
python3 scripts/summarize.py --id 1 --batch "$SRT_OUTPUT_DIR/batch_status_1_2.json" --phase db_inserting

此處 init_batch 1 2 選的是 manifest.files 的索引 1 到 2。--id 1 是該列的管道 file_id（該列的 id 欄位——以連續 id 產生的清單通常就是 1）。驗證多檔行為時可再對另一列使用 --id 2。成功寫入 DB 後，預期是每個唯一 chunk_id 一列，重新執行不應產生重複列。

階段順序：chunking → summarizing → embedding → db_inserting。

驗證

變更管道行為前，先跑本地回歸測試：

.venv/bin/pytest -q
.venv/bin/python -m compileall -q scripts tests

涵蓋範圍包括：設定檔載入、Smart Merge 小型檔案輸出形狀、狀態檔 sidecar 鎖定、檢查點恢復安全性、部分摘要阻擋、嵌入回應驗證、記錄驗證，以及 LanceDB 合併插入冪等性。

可選：參數實驗

若要快速實驗區塊／摘要參數、不走完整 LanceDB 正式寫入，請見儲存庫 README 中 chunk_test_runner.py 與 chunk_test_suite.py 相關章節。

下一步