# Ubuntu / Debian
sudo apt update && sudo apt install -y build-essential cmake git libsdl2-dev

# CentOS / RHEL / Rocky
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y cmake git SDL2-devel

# macOS (Homebrew)
brew install cmake git sdl2

git clone --depth 1 --branch v1.5.4 https://github.com/ggerganov/whisper.cpp
cd whisper.cpp

# 下载量化模型（示例：small 多语言 q5_1，约 488 MB）
bash ./models/download-ggml-model.sh small.q5_1
# 仅需英文场景可下载 base.en.q5_1（约 142 MB），推理更快

# 仅 CPU 推理（默认开启 AVX2/NEON 自动检测）
cmake -B build -DWHISPER_SDL2=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j$(nproc)

# 如需 GPU 加速（CUDA/Metal/Vulkan），参考官方 CMake 选项追加：
# -DGGML_CUDA=ON / -DGGML_METAL=ON / -DGGML_VULKAN=ON

./build/bin/whisper-cli -m models/ggml-small.q5_1.bin 
  -f samples/jfk.wav -l auto -otxt

./build/bin/whisper-stream 
  -m models/ggml-small.q5_1.bin 
  -t 6 
  --step 500 
  --length 5000 
  --keep 2000 
  --vad-thold 0.6 
  --max-len 60 
  -l auto 
  --output-txt 
  --output-file meeting_$(date +%F_%H-%M)

ffmpeg -f pulse -i "ZoomAudioDevice" 
  -f s16le -ar 16000 -ac 1 - | 
./build/bin/whisper-stream -m models/ggml-small.q5_1.bin -f - -t 6 --step 500 -l auto

-l auto  # 启动参数

// 监听 Unix Domain Socket / HTTP 控制接口
void on_language_change(const char* new_lang) {
    params.language = new_lang;   // 如 "en" -> "zh"
    params.detect_language = 0;   // 关闭自动检测
    // 下一轮 whisper_full() 即生效
}

[Unit]
Description=Whisper.cpp Real-time STT (%i)
After=network.target sound.target

[Service]
Type=simple
User=whisper
WorkingDirectory=/opt/whisper.cpp
ExecStart=/opt/whisper.cpp/build/bin/whisper-stream 
  -m models/ggml-small.q5_1.bin 
  -t 6 --step 500 --length 5000 --keep 2000 
  --vad-thold 0.6 -l %i 
  --output-txt --output-file /var/log/whisper/meeting_%%Y-%%m-%%d_%%H-%%M
Restart=on-failure
RestartSec=5
StandardOutput=append:/var/log/whisper/stream_%i.log
StandardError=append:/var/log/whisper/stream_%i.err

[Install]
WantedBy=multi-user.target

systemctl enable --now whisper-stream@zh
systemctl enable --now whisper-stream@en
# 切换语言：systemctl stop whisper-stream@zh && systemctl start whisper-stream@en

# 1. 克隆与编译
git clone --depth 1 --branch v1.5.4 https://github.com/ggerganov/whisper.cpp
cd whisper.cpp && cmake -B build -DWHISPER_SDL2=ON && cmake --build build -j

# 2. 下载模型
bash ./models/download-ggml-model.sh small.q5_1

# 3. 单命令启动会议转写（中英自动检测）
./build/bin/whisper-stream -m models/ggml-small.q5_1.bin -t 6 
  --step 500 --length 5000 --keep 2000 --vad-thold 0.6 -l auto 
  --output-txt --output-file meeting_$(date +%F_%H-%M)

# 4. 切换至纯英文模式（无需重新编译）
# 方案 A：重启进程 -l en
# 方案 B：控制接口动态修改 params.language = "en"

graph LR
    A[硬件采集 48kHz/24bit] --> B[重采样 16kHz/16bit]
    B --> C[自动增益控制 AGC]
    C --> D[降噪 - RNNoise / DeepFilterNet]
    D --> E[回声消除 AEC - WebRTC AEC3 / SpeexDSP]
    E --> F[语音活动检测 VAD - Silero VAD / WebRTC VAD]
    F --> G[音频分流器 Tee]
    G --> H[Whisper.cpp 推理进程]
    G --> I[原始录音归档 WAV/OPUS]
    G --> J[实时监听/字幕推流]

context.modules = [
    { name = libpipewire-module-filter-chain
      args = {
        node.name = "stt_preprocess"
        media.class = "Audio/Sink"
        filter.graph = "
            # 1. 强制单声道 16kHz
            channelmix = filter.channelmix { channels = 1 }
            resample = filter.resample { rate = 16000 }
            # 2. AGC 目标 -24 dBFS (EBU R128)
            agc = filter.ladspa { plugin = "sc4m" label = "sc4m_1" control = { -24, 12, 6, 3, 0, 1 } }
            # 3. RNNoise 降噪 (需 pipewire-audio-processing-modules)
            denoise = filter.ladspa { plugin = "rnnoise" label = "rnnoise" }
            # 4. WebRTC AEC3 (参考信号来自监听回环)
            aec = filter.webrtc-aec { playback.node = "monitor_loopback" }
        "
        capture.props = { node.target = "alsa_input.usb-Respeaker_4_Mic_Array..." }
    }
]

# 利用 GStreamer 实现带元数据的多路分发
gst-launch-1.0 
  pulsesrc device=stt_preprocess.monitor ! 
  audio/x-raw,format=S16LE,rate=16000,channels=1 ! 
  tee name=t 
  t. ! queue ! 
    appsink name=whisper_zh emit-signals=true caps="audio/x-raw,format=S16LE,rate=16000,channels=1" 
  t. ! queue ! 
    appsink name=whisper_en emit-signals=true caps="audio/x-raw,format=S16LE,rate=16000,channels=1" 
  t. ! queue ! 
    opusenc bitrate=24000 ! oggmux ! filesink location=archive/meeting_$(date +%s).ogg

graph TB
    subgraph 单机版
        S1[Whisper-stream] --> S2[(本地文件)]
    end

    subgraph 主备高可用
        M1[Active] --> M3[(共享存储 NFS/JuiceFS)]
        M2[Standby] -.-> M3
        M4[Keepalived/VIP] --> M1
        M4 --> M2
    end

    subgraph 微服务集群版 K8s
        GW[API Gateway / Ingress] --> LB[Service: whisper-stt]
        LB --> P1[Pod: whisper-worker-x86]
        LB --> P2[Pod: whisper-worker-arm]
        LB --> P3[Pod: whisper-worker-gpu]
        P1 --> Redis[(Redis Stream: 任务队列)]
        P2 --> Redis
        P3 --> Redis
        Redis --> CM[ConfigMap: 模型版本/参数]
        CM --> P1
        CM --> P2
        CM --> P3
        P1 --> S3[(MinIO/S3: 结果/审计日志)]
        P2 --> S3
        P3 --> S3
        MON[Prometheus + Grafana] --> P1
        MON --> P2
        MON --> P3
    end

# values.yaml 核心片段
replicaCount: 3
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 20
  targetCPUUtilizationPercentage: 65
  targetMemoryUtilizationPercentage: 70

resources:
  limits:
    cpu: "4000m"
    memory: "8Gi"
  requests:
    cpu: "2000m"
    memory: "4Gi"

model:
  name: "ggml-small.q5_1.bin"
  # 支持 OCI 镜像分发模型，避免镜像层过大
  image: "registry.internal/whisper-models/small.q5_1:v1.5.4"
  mountPath: "/models"

env:
  - name: WHISPER_THREADS
    value: "6"
  - name: WHISPER_STEP_MS
    value: "500"
  - name: WHISPER_LANGUAGE
    valueFrom:
      configMapKeyRef:
        name: whisper-config
        key: default_lang
        optional: true

# 亲和性：优先调度到 AVX2/AMX/NEON 节点
affinity:
  nodeAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        preference:
          matchExpressions:
            - key: "cpu-feature/avx2"
              operator: In
              values: ["true"]
            - key: "cpu-feature/amx"
              operator: In
              values: ["true"]

# 存活/就绪探针：检查推理线程是否卡死
livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5

groups:
- name: whisper-stt
  rules:
  - alert: WhisperHighRTF
    expr: histogram_quantile(0.99, rate(whisper_inference_duration_seconds_bucket[5m])) / 5.0 > 0.9
    for: 5m
    labels: { severity: warning }
    annotations:
      summary: "实时率逼近 1.0，可能出现积压"
      runbook: "https://wiki.internal/runbooks/whisper-high-rtf"

  - alert: WhisperModelLoadFail
    expr: increase(whisper_model_load_failures_total[10m]) > 0
    labels: { severity: critical }
    annotations:
      summary: "模型加载失败，检查 PVC 挂载/镜像拉取"

  - alert: WhisperQueueLag
    expr: kafka_consumergroup_lag{topic="stt-tasks"} > 100
    for: 2m
    labels: { severity: warning }
    annotations:
      summary: "任务积压，建议扩容 Worker"

{
  "type": "control",
  "action": "start_session",
  "session_id": "meet_20240115_001",
  "config": {
    "lang_policy": "auto",          // auto | fixed | manual_switch
    "fixed_lang": "zh",
    "diarization": true,
    "translate_target": "en",       // 同声传译目标语言
    "keyword_alert": ["机密", "合同金额", "收购"]
  }
}

{
  "type": "segment",
  "session_id": "meet_20240115_001",
  "seq": 1024,
  "start_ms": 125430,
  "end_ms": 129870,
  "lang": "zh",
  "lang_prob": 0.98,
  "speaker": "spk_0",
  "text": "下个季度的营收预测需要向上修正 5 个百分点。",
  "tokens": [
    {"t": "下个", "p": 0.99}, {"t": "季度", "p": 0.97}, ...
  ],
  "translation": {
    "en": "Next quarter's revenue forecast needs to be revised up by 5 percentage points."
  },
  "alerts": []
}

WEBVTT
Kind: captions
Language: zh

00:02:05.430 --> 00:02:09.870 <v spk_0><c.zh>下个季度的营收预测需要向上修正 5 个百分点。</c></v>
00:02:05.430 --> 00:02:09.870 <v spk_0><c.en>Next quarter's revenue forecast needs to be revised up by 5 percentage points.</c></v>
00:02:10.120 --> 00:02:14.560 <v spk_1><c.zh>同意，主要得益于新产品线的提前量产。</c></v>

#!/bin/bash
set -euo pipefail

ARCH=$(uname -m)
case "$ARCH" in
  aarch64)
    if lscpu | grep -q "Neoverse-N1"; then
      EXTRA_FLAGS="-mcpu=neoverse-n1 -DSVE=ON"
    elif lscpu | grep -q "FT-2000"; then
      EXTRA_FLAGS="-mtune=ft2000"
    else
      EXTRA_FLAGS="-DARM_NEON=ON"
    fi
    ;;
  x86_64)
    if lscpu | grep -q "Hygon"; then
      EXTRA_FLAGS="-march=znver3 -DAVX512=ON"
    else
      EXTRA_FLAGS="-march=native -DAVX2=ON"
    fi
    ;;
  loongarch64)
    EXTRA_FLAGS="-DLOONGARCH=ON -DLSX=ON -DLASX=ON"
    ;;
  *)
    EXTRA_FLAGS=""
    ;;
esac

cmake -B build 
  -DCMAKE_C_FLAGS_RELEASE="-O3 -DNDEBUG $EXTRA_FLAGS" 
  -DCMAKE_CXX_FLAGS_RELEASE="-O3 -DNDEBUG $EXTRA_FLAGS" 
  -DWHISPER_SDL2=OFF 
  -DGGML_OPENMP=ON 
  -DCMAKE_INSTALL_PREFIX=/usr/local/whisper.cpp

cmake --build build -j$(nproc) --target whisper-cli whisper-stream

Git Repo: whisper.cpp-enterprise
├── .github/workflows/
│   ├── ci-build.yml          # 多架构编译测试
│   ├── ci-model-test.yml     # 模型回归测试
│   └── cd-release.yml        # 发布镜像/Helm Chart
├── models/
│   ├── registry.yaml         # 模型元数据: 版本、量化、校验值、基准 CER
│   └── ggml-small.q5_1.bin   # Git LFS 存储
├── docker/
│   ├── Dockerfile.cpu
│   ├── Dockerfile.kunpeng
│   └── Dockerfile.hygon
├── helm/
│   └── whisper-stt/
└── tests/
    ├── audio_samples/        # 标准测试集 (含噪声/方言/代码切换)
    └── benchmarks/           # 性能基线脚本

# .github/workflows/ci-model-test.yml
jobs:
  accuracy-regression:
    runs-on: [self-hosted, linux, x64, avx2]  # 专用基准机
    steps:
      - uses: actions/checkout@v4
        with: { lfs: true }

      - name: Pull Test Dataset
        run: |
          dvc pull data/testset_20h.dvc  # 20h 标注会议数据，DVC 管理

      - name: Run Benchmark
        id: bench
        run: |
          python3 tests/benchmark.py 
            --model models/ggml-small.q5_1.bin 
            --dataset data/testset_20h 
            --threads 6 
            --output results.json

      - name: Compare with Baseline
        run: |
          python3 -c "
          import json, sys
          cur = json.load(open('results.json'))
          base = json.load(open('tests/baselines/small.q5_1.json'))
          cer_delta = cur['cer'] - base['cer']
          rtf_delta = cur['rtf'] - base['rtf']
          print(f'CER Δ: {cer_delta:.4f}, RTF Δ: {rtf_delta:.4f}')
          if cer_delta > 0.005 or rtf_delta > 0.05:
              sys.exit('REGRESSION DETECTED')
          "

      - name: Update Baseline (on tag push)
        if: startsWith(github.ref, 'refs/tags/v')
        run: |
          cp results.json tests/baselines/small.q5_1.json
          git config user.name "ci-bot"
          git commit -am "chore: update baseline for ${{ github.ref_name }}"
          git push

# Dockerfile.multiarch (BuildKit 语法)
# syntax = docker/dockerfile:1.7
ARG BASE_IMAGE=ubuntu:22.04
FROM --platform=$BUILDPLATFORM $BASE_IMAGE AS builder

ARG TARGETARCH
ARG TARGETVARIANT
RUN apt-get update && apt-get install -y --no-install-recommends 
    build-essential cmake git ca-certificates && rm -rf /var/lib/apt/lists/*

WORKDIR /src
COPY . .
RUN --mount=type=cache,target=/root/.cache 
    ./build_cn.sh  # 自动识别 TARGETARCH 注入编译旗帜

FROM --platform=$TARGETPLATFORM $BASE_IMAGE AS runtime
RUN apt-get update && apt-get install -y --no-install-recommends 
    libgomp1 libsdl2-2.0-0 libasound2 && rm -rf /var/lib/apt/lists/*
COPY --from=builder /usr/local/whisper.cpp /usr/local/whisper.cpp
ENV PATH="/usr/local/whisper.cpp/bin:${PATH}"
ENTRYPOINT ["whisper-stream"]

# 构建并推送多架构清单
docker buildx create --name multiarch --driver docker-container --use
docker buildx build 
  --platform linux/amd64,linux/arm64,linux/loong64 
  -t registry.internal/whisper-stt:v1.5.4-ent 
  --push .

# pii_sanitizer.py (Sidecar 容器 / gRPC Filter)
import re
from transformers import pipeline

ner = pipeline("ner", model="uer/roberta-base-finetuned-cluener2020", aggregation_strategy="simple")
PATTERNS = {
    "ID_CARD": r"d{17}[dXx]",
    "PHONE": r"1[3-9]d{9}",
    "BANK_CARD": r"d{16,19}",
    "CONTRACT_AMT": r"(合同|金额|报价).*?(d+[.,]?d*)s*(万|亿|元)",
}

def sanitize(text: str, lang: str) -> tuple[str, list]:
    entities = ner(text) if lang == "zh" else []
    spans = []
    for ent in entities:
        if ent['entity_group'] in ('PER', 'ORG', 'LOC'):
            spans.append((ent['start'], ent['end'], f"[{ent['entity_group']}]"))
    for name, regex in PATTERNS.items():
        for m in re.finditer(regex, text):
            spans.append((m.start(), m.end(), f"[{name}]"))
    # 合并重叠区间，替换
    spans.sort()
    out, last = [], 0
    for s, e, tag in spans:
        out.append(text[last:s])
        out.append(tag)
        last = e
    out.append(text[last:])
    return "".join(out), spans

graph LR
    A[Whisper Worker] --> B[结构化日志 JSON]
    B --> C[SM3 哈希链]
    C --> D[写入 Kafka Topic: audit-log]
    D --> E[Flink 流式校验]
    E --> F[落盘 ClickHouse / Elasticsearch]
    E --> G[定时上链/存证 区块链/可信时间戳]

graph LR
    A[会议实时转写] --> B[人工复核/编辑]
    B --> C[高质量平行语料库]
    C --> D[LoRA/Adapter 微调]
    D --> E[模型评估 CER/WER]
    E --> F{达标?}
    F -- 否 --> D
    F -- 是 --> G[灰度发布 Canary]
    G --> H[线上 A/B 测试]
    H --> I[全量替换]
    I --> A

# 1. 准备数据 (JSONL 格式)
# {"audio": "meeting_001.wav", "text": "下个季度营收预测上修五个百分点", "lang": "zh"}

# 2. 训练 LoRA Adapter (仅冻结 Encoder, 微调 Decoder 交叉注意力)
python -m whisper_finetune 
  --model_name_or_path openai/whisper-small 
  --train_data data/train.jsonl 
  --eval_data data/eval.jsonl 
  --output_dir ./lora-meeting-zh 
  --lora_r 16 --lora_alpha 32 --lora_dropout 0.05 
  --per_device_train_batch_size 8 
  --gradient_accumulation_steps 4 
  --learning_rate 1e-4 --num_train_epochs 3 
  --fp16 --gradient_checkpointing

# 3. 合并导出 GGML (需 whisper.cpp 支持 adapter 分支或手动合并权重)
python -m whisper_finetune.export_ggml 
  --base_model models/ggml-small.bin 
  --adapter ./lora-meeting-zh/adapter_model.bin 
  --output models/ggml-small-meeting-lora.q5_1.bin