設定¶

TranscriptFlow 透過環境變數與本機 config.json 設定。公開範本：

.env.example → 複製為 .env
scripts/config.example.json → 複製為專案根目錄 config.json

根目錄另有一份與 scripts 範本對齊的 config.example.json 方便取用；但當沒有本機設定檔時，config_loader 只會回退到 scripts/config.example.json。建議仍依下列方式從 scripts/config.example.json 複製。

不要提交機密

切勿提交真實 API 金鑰、.env、config.json、產出的 output/、LanceDB 目錄或批次狀態產物。共享範例只能保留佔位符（例如 replace-with-your-api-key）。

優先順序¶

解析方式對應 config_loader.get_config() / get_env_or_config：

環境變數對各鍵優先（含透過 python-dotenv／shell source 從 .env 載入的值）。
一次載入一整份 JSON — 若專案根目錄存在 config.json（或 TRANSCRIPTFLOW_CONFIG 指定路徑），就完整載入該檔；否則完整載入 scripts/config.example.json 作為唯一設定文件。
缺鍵使用程式內預設（呼叫端／schema 預設）— loader 不會把你的部分 config.json 與範例檔做 deep-merge。

實務意涵：若已有但不完整的 config.json，不會從 scripts/config.example.json 補洞。請複製完整範例再改，或對省略的鍵依賴環境變數與程式內預設。

模型清單

請優先在 config.json 使用 summarization.models，少用 shell 的 SUMMARIZATION_MODELS 環境變數。Shell 解析可能剝掉 JSON 雙引號。

不要把 API 金鑰放進會提交的 JSON。請在環境中設定 OPENAI_API_KEY 或 LITELLM_PROXY_KEY。

環境變數¶

從範本開始：

cp .env.example .env

重要變數（僅佔位符）：

變數	用途	範例（非機密）
`OPENAI_BASE_URL`	OpenAI 相容 API base	`https://api.openai.com`
`OPENAI_API_KEY`	聊天／嵌入驗證	`replace-with-your-api-key`
`LITELLM_PROXY_URL`	LiteLLM 類 proxy 的替代 base URL	（可選）
`LITELLM_PROXY_KEY`	替代 API 金鑰名稱	（可選）
`EMBEDDING_API_BASE`	嵌入與聊天分離時覆寫嵌入 base	（可選）
`EMBEDDING_MODEL`	嵌入模型名稱	`text-embedding-3-large`
`EMBEDDING_EXPECTED_DIM`	驗證用的預期向量維度	`3072`
`SRT_OUTPUT_DIR`	管道工作／輸出目錄	`./output`
`SRT_DB_PATH`	LanceDB 目錄	`./lancedb`
`SRT_MASTER_FILE`	主清單路徑	產生出的 `master_file_manifest.json` 路徑
`TRANSCRIPTFLOW_CONFIG`	覆寫 `config.json` 路徑	（可選）
`ALLOW_INSECURE_HTTP`	允許非本機端點使用非 HTTPS（僅開發）	`false`

載入方式：

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

主清單¶

paths.master_file／SRT_MASTER_FILE 必須指向管道可用的文件：

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

不能直接當正式輸入

examples/master_file_manifest.example.json 僅供示意。實際 loader 需要 { "files": [ { "id", "path_srt", "path_mp3", "filename_srt", "filename_mp3", … } ] }。請優先：

python3 scripts/generate_manifest.py --data-dir ./path/to/pairs --dry-run
python3 scripts/generate_manifest.py --data-dir ./path/to/pairs --output ./path/to/master_file_manifest.json

init_batch 會把 SRT 或 MP3 路徑不存在於磁碟的列標為永久失敗。索引 vs file_id 語意見快速開始。

設定檔¶

cp scripts/config.example.json config.json

config.json 已被 gitignore。範例檔是模型、批次大小、路徑、重試與看門狗上限的公開範本。

API¶

鍵	角色
`api.base_url`	環境未設定時的預設 base URL
`api.chat_completions_path`	聊天路徑（預設 `/v1/chat/completions`）
`api.embeddings_path`	嵌入路徑（預設 `/v1/embeddings`）
`api.models_path`	模型列表路徑
`api.api_timeout`	HTTP 逾時（秒）

相容 OpenAI、LiteLLM Proxy、OpenRouter、vLLM、Ollama 相容伺服器等閘道。

區塊切割（Smart Merge）¶

鍵	角色	範例預設
`chunking.smart_merge_window_size`	每次合併視窗的字幕條目數	`5`
`chunking.smart_merge_strong_pct`	強語意邊界百分位數	`0.02`
`chunking.smart_merge_weak_pct`	較弱候選邊界百分位數	`0.05`
`chunking.smart_merge_min_sentences`	接受邊界前的最小句數	`8`
`chunking.smart_merge_noise_drop_len`	丟棄極短雜訊段落	`2`
`chunking.smart_merge_noise_weak_len`	視為弱邊界候選的短段落	`3`
`chunking.min_chunks` / `chunking.max_chunks`	區塊數量上下限	`2` / `200`

這些旋鈕讓同一管道能適應不同節奏的檔案庫：訪談、講座、播客、座談、課程或混合長篇媒體。

摘要¶

鍵	角色
`summarization.models`	有序聊天模型清單（備援／輪替）
`summarization.participant_chunks`	講者擷取用的區塊上下文
`summarization.max_retries`	每區塊重試額度
`summarization.concurrency`	摘要工作者並發
`summarization.timeout_sec`	每次呼叫逾時

嵌入¶

鍵	角色
`embedding.model`	嵌入模型名稱
`embedding.expected_dim`	必要向量維度
`embedding.batch_max_size`	每次嵌入請求的最大文字數
`embedding.timeout`	請求逾時（秒）

請讓 EMBEDDING_EXPECTED_DIM／embedding.expected_dim 與實際呼叫的模型一致。

路徑與資料表¶

鍵	角色
`paths.output_dir`	工作輸出目錄
`paths.db_path`	LanceDB 路徑
`paths.master_file`	清單 JSON
`paths.data_dir`	SRT／資料根目錄
`paths.backup_dir`	Lance 備份目錄
`tables.final_db`	最終資料表名稱（範例：`psychology_kb`）

設定了 SRT_OUTPUT_DIR、SRT_DB_PATH、SRT_MASTER_FILE 等環境變數時，會覆寫對應路徑設定。

看門狗與階段並發¶

鍵	角色
`phase_concurrency.phase1_chunking`	區塊切割最大並發
`phase_concurrency.phase2_summarizing`	摘要最大並發
`phase_concurrency.phase3_embedding`	嵌入最大並發
`phase_concurrency.phase4_db_insert`	DB 寫入最大並發
`watchdog.max_working_time_sec`	卡住任務重設前的逾時（範例預設 `600`）
`monitoring.heartbeat_interval_sec`	長任務心跳間隔

可選區段¶

scripts/config.example.json 另有核心四階段之外的工具設定：

區段	用途
`chunk_test`	參數測試 runner 並發
`srt_quality`	多模型 SRT 品質審查視窗／模型
`evaluation`	區塊品質與摘要保真度評判模型

不要提交的內容¶

請保持本機：

.env
config.json
test_params_suite.json（若你從範例建立）
產出的 output/、LanceDB 目錄與批次狀態產物

只把操作者指向範本：

僅文件站¶

文件建置依賴與執行期管道分離（文件站不改動 requirements.txt）：

pip install -r requirements-docs.txt
mkdocs serve

完整管道安裝路徑見快速開始。