flowchart TB
    subgraph Upstream["上游调用方"]
        AIOrch["AI-Orchestrator<br/>对话编排"]
        ConvSvc["Conversation-Service<br/>会话管理"]
        WebApp["Web应用<br/>直接调用"]
    end

    subgraph VoiceEngine["Voice Engine 服务层 (main.py)"]
        FastAPI["FastAPI应用<br/>端口8004"]
        Middleware["中间件层<br/>CORS/日志/成本追踪/限流/幂等性"]

        subgraph Routers["路由层 (app/routers)"]
            VoiceStreamRouter["VoiceStreamRouter<br/>/api/v1/voice/stream"]
            EmotionRouter["EmotionRouter<br/>/api/v1/emotion/*"]
            DiarizationRouter["DiarizationRouter<br/>/api/v1/diarization/*"]
            FullDuplexRouter["FullDuplexRouter<br/>/api/v1/full-duplex"]
        end

        FastAPI --> Middleware
        Middleware --> Routers
    end

    subgraph Core["核心引擎层 (app/core)"]
        VoiceEngineCore["VoiceEngine<br/>核心协调器"]

        subgraph Engines["引擎实例"]
            ASREngine["ASREngine<br/>Whisper识别"]
            TTSEngine["TTSEngine<br/>Edge TTS合成"]
            VADEngine["VADEngine<br/>Silero VAD检测"]
        end

        subgraph Resilience["可靠性组件"]
            CircuitBreaker["CircuitBreaker<br/>熔断器"]
            Retry["RetryWithBackoff<br/>重试机制"]
            Observability["Observability<br/>指标追踪"]
        end

        VoiceEngineCore --> Engines
        VoiceEngineCore --> Resilience
    end

    subgraph Services["服务层 (app/services)"]
        ASRService["ASRService<br/>识别服务"]
        TTSService["TTSService<br/>合成服务"]
        VADService["VADService<br/>VAD服务"]
        StreamingASRService["StreamingASRService<br/>流式识别"]
        RealtimeVoiceService["RealtimeVoiceService<br/>实时语音流"]
        MultiVendorAdapter["MultiVendorAdapter<br/>多厂商适配"]
        EmotionRecognitionService["EmotionRecognitionService<br/>情感识别"]
        DiarizationService["DiarizationService<br/>说话人分离"]
    end

    subgraph Infrastructure["基础设施层 (app/infrastructure)"]
        TTSCache["TTSRedisCache<br/>LRU缓存"]
        Redis[(Redis<br/>缓存存储)]
    end

    subgraph Models["模型层"]
        WhisperModel["Whisper Model<br/>Transformers/base"]
        SileroVAD["Silero VAD<br/>PyTorch Hub"]
        EdgeTTS["Edge TTS<br/>在线服务"]
        AzureSpeech["Azure Speech<br/>备用降级"]
    end

    AIOrch -->|"HTTP REST<br/>批量ASR/TTS"| FastAPI
    ConvSvc -->|"HTTP REST<br/>TTS合成"| FastAPI
    WebApp -->|"WebSocket<br/>实时语音流"| FastAPI

    Routers --> Services
    Services --> Core

    VoiceStreamRouter --> RealtimeVoiceService
    EmotionRouter --> EmotionRecognitionService
    DiarizationRouter --> DiarizationService

    ASRService --> ASREngine
    TTSService --> TTSEngine
    VADService --> VADEngine
    StreamingASRService --> ASREngine
    StreamingASRService --> VADEngine
    RealtimeVoiceService --> StreamingASRService

    ASREngine --> WhisperModel
    TTSEngine --> EdgeTTS
    VADEngine --> SileroVAD

    TTSService --> TTSCache
    TTSCache --> Redis

    MultiVendorAdapter --> AzureSpeech
    ASRService -.备用.-> MultiVendorAdapter
    TTSService -.备用.-> MultiVendorAdapter

    style Upstream fill:#e3f2fd
    style VoiceEngine fill:#fff3e0
    style Core fill:#f3e5f5
    style Services fill:#e1f5fe
    style Infrastructure fill:#e8f5e9
    style Models fill:#fce4ec
    style Resilience fill:#fff9c4

Client → FastAPI → main.speech_to_text()
       → get_voice_engine()（依赖注入）
       → VoiceEngine.speech_to_text()
       → CircuitBreaker.call()（熔断器包装）
       → asyncio.wait_for()（超时控制）
       → ASREngine.transcribe()
       → WhisperProcessor/WhisperModel
       → 返回识别结果

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant FastAPI as FastAPI主应用
    participant VoiceEngine as VoiceEngine核心
    participant CircuitBreaker as 熔断器
    participant ASREngine as ASREngine
    participant Whisper as Whisper Model
    participant Metrics as Observability

    Client->>FastAPI: POST /asr<br/>文件上传{audio, language, model}
    FastAPI->>FastAPI: 验证请求参数
    FastAPI->>FastAPI: get_voice_engine()获取实例

    FastAPI->>VoiceEngine: speech_to_text(audio_data, language, model)

    VoiceEngine->>Metrics: @track_asr_metrics开始记录
    VoiceEngine->>VoiceEngine: stats["total_asr_requests"] += 1

    alt 熔断器启用
        VoiceEngine->>CircuitBreaker: call(_do_transcribe)
        CircuitBreaker->>CircuitBreaker: 检查熔断器状态

        alt 熔断器 OPEN
            CircuitBreaker-->>VoiceEngine: 抛出CircuitBreakerOpenError
            VoiceEngine-->>FastAPI: HTTPException(503, "Circuit breaker open")
            FastAPI-->>Client: 503 Service Unavailable
        end
    end

    CircuitBreaker->>VoiceEngine: 执行_do_transcribe()
    VoiceEngine->>VoiceEngine: asyncio.wait_for(timeout=ASR_TIMEOUT_SECONDS)

    VoiceEngine->>ASREngine: transcribe(audio_data, language, model)

    ASREngine->>ASREngine: _bytes_to_array()<br/>转换音频格式

    alt 流式模式启用
        ASREngine->>ASREngine: _transcribe_with_model()
        ASREngine->>Whisper: processor(audio, sampling_rate)
        Whisper-->>ASREngine: input_features

        ASREngine->>Whisper: model.generate(<br/>input_features,<br/>num_beams=5,<br/>language=zh)
        Whisper->>Whisper: 编码器：提取音频特征
        Whisper->>Whisper: 解码器：beam search生成文本
        Whisper-->>ASREngine: predicted_ids

        ASREngine->>Whisper: processor.batch_decode(predicted_ids)
        Whisper-->>ASREngine: transcription text
    else 批处理模式
        ASREngine->>Whisper: pipeline(audio_array)
        Whisper-->>ASREngine: {text, chunks, language}
    end

    ASREngine-->>VoiceEngine: {text, chunks, language, duration}

    alt 超时
        VoiceEngine->>VoiceEngine: asyncio.TimeoutError
        VoiceEngine-->>FastAPI: Exception("ASR timeout")
        FastAPI-->>Client: 500 Internal Server Error
    end

    VoiceEngine->>VoiceEngine: stats["successful_asr"] += 1
    VoiceEngine->>VoiceEngine: stats["total_audio_duration"] += duration

    VoiceEngine-->>FastAPI: {text, chunks, language, duration}
    FastAPI-->>Client: 200 OK + JSON结果

    VoiceEngine->>Metrics: @track_asr_metrics记录延迟

    Note over Client,Metrics: 总延迟：600-1000ms<br/>- 音频转换: 50-100ms<br/>- Whisper识别: 500-800ms<br/>- 其他: 50-100ms

Client → FastAPI → TTSRouter.synthesize_speech()
       → TTSService.synthesize()
       → TTSRedisCache.get()（查询缓存）
       → Redis.get()
       → 如果缓存未命中：
           → TTSService._synthesize_with_edge()
           → edge_tts.Communicate.stream()
           → TTSRedisCache.set()（存入缓存）
       → 返回 TTSResponse

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant Router as TTSRouter
    participant Service as TTSService
    participant Cache as TTSRedisCache
    participant Redis as Redis
    participant EdgeTTS as Edge TTS

    Client->>Router: POST /api/v1/tts/synthesize<br/>{text, voice, rate, pitch, format}
    Router->>Router: 验证请求参数
    Router->>Service: synthesize(request)

    Service->>Service: 设置默认值<br/>voice=zh-CN-XiaoxiaoNeural<br/>rate=+0%, pitch=+0Hz, format=mp3

    Service->>Cache: get(text, voice, rate, pitch, format)
    Cache->>Cache: _generate_key()<br/>SHA256(text+voice+rate+pitch+format)
    Cache->>Redis: GET tts:cache:{hash}

    alt 缓存命中
        Redis-->>Cache: audio_bytes
        Cache->>Redis: HINCRBY {hash}:stats hits 1
        Cache->>Redis: ZADD tts:lru {hash} {timestamp}
        Cache-->>Service: audio_bytes
        Service->>Service: base64.b64encode(audio_bytes)
        Service-->>Router: TTSResponse{audio_base64, cached=true}
        Router-->>Client: 200 OK + TTSResponse

        Note over Client,EdgeTTS: 缓存命中路径延迟：< 10ms<br/>- Redis查询: 2-5ms<br/>- Base64编码: 2-3ms<br/>- JSON序列化: 1-2ms

    else 缓存未命中
        Redis-->>Cache: None
        Cache-->>Service: None

        Service->>Service: _synthesize_with_edge()
        Service->>EdgeTTS: Communicate(text, voice, rate, pitch)
        EdgeTTS->>EdgeTTS: 建立WebSocket连接
        EdgeTTS->>EdgeTTS: 发送SSML请求

        loop 流式接收音频
            EdgeTTS->>EdgeTTS: 生成音频块
            EdgeTTS-->>Service: chunk["data"]
            Service->>Service: 累积音频块
        end

        EdgeTTS-->>Service: 所有音频块
        Service->>Service: b"".join(audio_chunks)

        Service->>Cache: set(text, voice, rate, pitch, format, audio_data)
        Cache->>Cache: 检查缓存大小

        alt 缓存超限
            Cache->>Cache: _evict_lru(needed_size)
            Cache->>Redis: ZRANGE tts:lru 0 -1（获取LRU列表）
            Redis-->>Cache: lru_keys

            loop 淘汰直到腾出空间
                Cache->>Redis: DELETE {key}
                Cache->>Redis: DELETE {key}:stats
                Cache->>Redis: ZREM tts:lru {key}
            end

            Cache->>Cache: logger.info("LRU evicted")
        end

        Cache->>Redis: SETEX tts:cache:{hash} {ttl} {audio_data}
        Cache->>Redis: HMSET {hash}:stats {metadata}
        Cache->>Redis: ZADD tts:lru {hash} {timestamp}

        Service->>Service: base64.b64encode(audio_data)
        Service-->>Router: TTSResponse{audio_base64, cached=false}
        Router-->>Client: 200 OK + TTSResponse

        Note over Client,EdgeTTS: 缓存未命中路径延迟：200-500ms<br/>- Edge TTS合成: 150-400ms<br/>- Redis写入: 10-20ms<br/>- Base64编码: 20-30ms
    end

Client → WebSocket 握手 → FastAPI WebSocket
       → VoiceStreamRouter.websocket_voice_stream()
       → get_realtime_service()（延迟初始化）
       → RealtimeVoiceService.handle_stream()
       → 循环接收音频帧（PCM 16kHz 16bit）
           → 累积音频 buffer
           → VADService.detect() 检测语音活动
           → 检测到静音（silence_duration 秒）→ 触发识别
           → StreamingASRService.recognize_segment()
           → WhisperModel.transcribe()
           → 返回 transcription 消息（JSON）
           → 定期发送 heartbeat 消息
       → 会话超时或客户端断开
       → cleanup_session() 清理资源
       → 关闭 WebSocket

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant WS as WebSocket Server
    participant RealtimeService as RealtimeVoiceService
    participant StreamingASR as StreamingASRService
    participant VADEngine as VADEngine
    participant WhisperModel as Whisper Model

    Client->>WS: WebSocket 握手<br/>ws://host:8004/api/v1/voice/stream
    WS-->>Client: 101 Switching Protocols

    WS->>WS: 生成 session_id = uuid.uuid4()
    WS->>WS: get_realtime_service() 延迟初始化

    alt RealtimeVoiceService 首次初始化
        WS->>RealtimeService: 创建实例<br/>(sample_rate=16000, vad_threshold=0.3,<br/>min_speech_duration=0.5s, silence_duration=0.8s)
        RealtimeService->>StreamingASR: 初始化 StreamingASRService
        RealtimeService->>VADEngine: 初始化 VADEngine
    end

    WS->>RealtimeService: handle_stream(websocket, session_id)

    RealtimeService->>RealtimeService: 初始化会话状态<br/>audio_buffer=[]<br/>last_speech_time=None<br/>is_speaking=False

    loop 音频流处理（直到断开或超时）
        Client->>WS: 音频帧（binary, PCM 16kHz 16bit mono）
        WS->>RealtimeService: 接收音频数据

        RealtimeService->>RealtimeService: audio_buffer.append(audio_frame)
        RealtimeService->>RealtimeService: buffer_duration += frame_duration

        alt buffer 达到 min_chunk_size（2秒）
            RealtimeService->>RealtimeService: combined_audio = b"".join(audio_buffer)

            RealtimeService->>VADEngine: detect(combined_audio, threshold=0.3)
            VADEngine->>VADEngine: _load_audio() 转换为 numpy
            VADEngine->>VADEngine: Silero VAD 推理（滑动窗口512）
            VADEngine->>VADEngine: _merge_segments() 合并连续片段
            VADEngine-->>RealtimeService: segments[{start, end, confidence}]

            alt 检测到语音（len(segments) > 0）
                RealtimeService->>RealtimeService: is_speaking = True
                RealtimeService->>RealtimeService: last_speech_time = current_time
            else 无语音（len(segments) == 0）
                alt is_speaking == True
                    RealtimeService->>RealtimeService: silence_elapsed = current_time - last_speech_time

                    alt silence_elapsed >= silence_duration（0.8s）
                        Note over RealtimeService: 静音超过阈值，触发识别

                        RealtimeService->>StreamingASR: recognize_segment(<br/>audio_segment, language="zh")

                        StreamingASR->>StreamingASR: detect_speech() 二次VAD确认
                        StreamingASR->>VADEngine: 提取语音段
                        VADEngine-->>StreamingASR: AudioSegment[audio, start, end]

                        StreamingASR->>WhisperModel: transcribe(<br/>segment.audio,<br/>language="zh",<br/>beam_size=5)
                        WhisperModel->>WhisperModel: 编码器：提取音频特征
                        WhisperModel->>WhisperModel: 解码器：beam search生成文本
                        WhisperModel-->>StreamingASR: segments[{text, start, end}]

                        StreamingASR->>StreamingASR: 提取文本 + 计算置信度
                        StreamingASR-->>RealtimeService: {text, confidence, language, start_time, end_time}

                        RealtimeService-->>WS: {type:"transcription",<br/>text:"识别结果",<br/>confidence:0.92,<br/>session_id}
                        WS-->>Client: transcription（JSON）

                        RealtimeService->>RealtimeService: 清空 audio_buffer
                        RealtimeService->>RealtimeService: is_speaking = False
                    end
                end
            end
        end

        alt heartbeat_interval 到期（1秒）
            RealtimeService-->>WS: {type:"heartbeat",<br/>buffer_duration:2.3s,<br/>is_speaking:true,<br/>session_id}
            WS-->>Client: heartbeat（JSON）
        end

        alt session_timeout 超时（300秒）
            RealtimeService-->>WS: {type:"timeout",<br/>message:"Session timeout",<br/>session_id}
            WS-->>Client: timeout（JSON）
            Note over RealtimeService: 退出循环
        end
    end

    alt 客户端断开连接
        Client-->>WS: WebSocketDisconnect
    end

    WS->>RealtimeService: cleanup_session(session_id)
    RealtimeService->>RealtimeService: 清理 audio_buffer
    RealtimeService->>RealtimeService: 释放会话资源

    WS-->>Client: WebSocket 关闭

    Note over Client,WhisperModel: 关键延迟指标：<br/>- VAD检测: 50-100ms<br/>- 静音触发延迟: 0.8s<br/>- Whisper识别: 500-800ms<br/>- 总响应延迟: 1.4-1.7s（从说话结束到返回结果）

classDiagram
    class VoiceEngine {
        -ASRService asr_service
        -TTSService tts_service
        -VADService vad_service
        -dict stats
        +initialize()
        +speech_to_text(audio_data, language, model)
        +text_to_speech(text, voice, rate, pitch)
        +text_to_speech_stream(text, voice, rate, pitch)
        +detect_voice_activity(audio_data, threshold)
        +get_stats()
    }

    class ASRService {
        -string provider
        -WhisperModel model
        -VADService vad_service
        +recognize(request)
        +recognize_from_bytes(audio_data, language, enable_vad)
        -_recognize_with_whisper()
        -_recognize_with_azure()
    }

    class ASREngine {
        -string model_name
        -WhisperProcessor processor
        -WhisperModel model
        -list audio_buffer
        +transcribe(audio_data, sample_rate, return_timestamps)
        +transcribe_stream(audio_stream)
    }

    class StreamingASRService {
        -WhisperModel whisper_model
        -torch.Model vad_model
        -list audio_buffer
        -float buffer_duration
        +process_stream(audio_generator)
        -_process_audio_chunk()
        -_merge_segments()
    }

    class TTSService {
        -string provider
        -TTSCache cache
        +synthesize(request)
        +synthesize_stream(request)
        -_synthesize_with_edge()
        -_synthesize_with_azure()
    }

    class TTSEngine {
        -string provider
        -string voice
        -string rate
        -string pitch
        +synthesize(text, output_format)
        +synthesize_stream(text, chunk_size)
        -_synthesize_edge_tts()
        -_synthesize_edge_tts_stream()
    }

    class VADService {
        -torch.Model model
        -int sample_rate
        +detect(audio_data)
        +detect_from_bytes(audio_data)
        -_preprocess_audio()
    }

    class MultiVendorAdapter {
        -string preferred_asr
        -string preferred_tts
        -AzureSpeechService azure_service
        -EdgeTTSService edge_tts_service
        +recognize(audio_data, language, model_size)
        +synthesize(text, voice, rate, pitch)
    }

    class ASRRequest {
        +string audio_url
        +string audio_base64
        +string language
        +bool enable_vad
        +string task
    }

    class ASRResponse {
        +string text
        +string language
        +float confidence
        +list segments
        +int duration_ms
        +int processing_time_ms
    }

    class TTSRequest {
        +string text
        +string voice
        +string rate
        +string pitch
        +string format
    }

    class TTSResponse {
        +string audio_base64
        +int duration_ms
        +int processing_time_ms
        +bool cached
    }

    VoiceEngine "1" *-- "1" ASRService
    VoiceEngine "1" *-- "1" TTSService
    VoiceEngine "1" *-- "1" VADService

    ASRService "1" *-- "1" ASREngine
    ASRService "1" *-- "1" VADService
    ASRService ..> MultiVendorAdapter : uses

    TTSService "1" *-- "1" TTSEngine
    TTSService ..> MultiVendorAdapter : uses

    ASRService ..> ASRRequest : receives
    ASRService ..> ASRResponse : returns
    TTSService ..> TTSRequest : receives
    TTSService ..> TTSResponse : returns

if enable_vad:
    vad_result = await self.vad_service.detect_from_bytes(audio_data)
    if vad_result.speech_ratio < 0.1:
        logger.warning(f"Low speech ratio: {vad_result.speech_ratio:.2%}")

cached_audio_bytes = self.cache.get(text, voice, rate, pitch, format)
if cached_audio_bytes:
    logger.info("TTS cache hit")
    return TTSResponse(audio_base64=..., cached=True, processing_time_ms=<10)

# 缓存未命中：调用 Edge TTS
audio_data = await self._synthesize_with_edge(request)
self.cache.set(text, voice, rate, pitch, format, audio_data)

chunk_duration = 5.0  # 5 秒缓冲

async for audio_chunk in audio_generator:
    audio_buffer.append(audio_chunk)
    buffer_duration += len(audio_chunk) / (16000 * 2)

    if buffer_duration >= chunk_duration:
        audio_data = b"".join(audio_buffer)
        result = await self._transcribe(audio_data)
        yield {"type": "partial_result", "text": result["text"]}
        audio_buffer = []
        buffer_duration = 0.0

self.model = WhisperModel(
    model_name="base",
    device="cuda",  # GPU 加速
    compute_type="int8",  # int8 量化
)

segments, info = self.model.transcribe(
    audio,
    beam_size=5,  # 默认 5，平衡准确率和速度
)

# MultiVendorAdapter 自动降级
if self.provider == "edge":
    try:
        audio_data = await self._synthesize_with_edge(request)
    except Exception as e:
        logger.warning(f"Edge TTS failed: {e}, fallback to Azure")
        audio_data = await self._synthesize_with_azure(request)

class MultiVendorAdapter:
    async def recognize(self, audio_data, language):
        if self.preferred_asr == "faster-whisper":
            try:
                return await self._recognize_with_whisper(audio_data)
            except Exception as e:
                logger.warning(f"Whisper failed: {e}, fallback to Azure")
                return await self._recognize_with_azure(audio_data)
        else:
            return await self._recognize_with_azure(audio_data)

{
    "audio_base64": "UklGRiQAAABXQVZFZm10...",
    "language": "zh",
    "enable_vad": true,
    "task": "transcribe"
}

{
    "text": "你好，世界",
    "language": "zh",
    "confidence": 0.95,
    "segments": [
        {
            "start": 0.0,
            "end": 1.5,
            "text": "你好，世界"
        }
    ],
    "duration_ms": 1500,
    "processing_time_ms": 350
}

async def recognize(self, request: ASRRequest) -> ASRResponse:
    """
    语音识别（批量模式）
    """
    start_time = time.time()

    # 1. 解码音频数据
    if request.audio_base64:
        audio_data = base64.b64decode(request.audio_base64)
    elif request.audio_url:
        audio_data = await self._download_audio(request.audio_url)
    else:
        raise ValueError("必须提供audio_base64或audio_url")

    # 2. VAD预处理（可选）
    if request.enable_vad:
        vad_result = await self.vad_service.detect_from_bytes(audio_data)
        if vad_result.speech_ratio < 0.1:
            # 几乎没有语音内容
            logger.warning(f"Low speech ratio: {vad_result.speech_ratio:.2%}")

    # 3. Whisper识别
    if self.provider == "whisper":
        result = await self._recognize_with_whisper(audio_data, request.language, request.task)
    elif self.provider == "azure":
        result = await self._recognize_with_azure(audio_data, request.language)
    else:
        raise ValueError(f"Unsupported ASR provider: {self.provider}")

    processing_time_ms = (time.time() - start_time) * 1000

    return ASRResponse(
        text=result["text"],
        language=result["language"],
        confidence=result.get("confidence"),
        segments=result.get("segments"),
        duration_ms=result.get("duration_ms", 0),
        processing_time_ms=processing_time_ms,
    )

async def _recognize_with_whisper(
    self, audio_data: bytes, language: str, task: str
) -> dict:
    """使用Faster-Whisper识别"""
    import io
    import numpy as np
    from pydub import AudioSegment

    # 1. 加载音频
    audio = AudioSegment.from_file(io.BytesIO(audio_data))

    # 2. 转换为16kHz单声道
    audio = audio.set_frame_rate(16000).set_channels(1)

    # 3. 转换为numpy数组
    samples = np.array(audio.get_array_of_samples(), dtype=np.float32)
    samples = samples / 32768.0  # 归一化到[-1, 1]

    # 4. Whisper识别
    segments, info = self.model.transcribe(
        samples,
        language=language,
        task=task,
        beam_size=5,
        vad_filter=True,  # 启用内置VAD
    )

    # 5. 构建结果
    text_segments = []
    full_text = []

    for segment in segments:
        text_segments.append({
            "start": segment.start,
            "end": segment.end,
            "text": segment.text.strip(),
        })
        full_text.append(segment.text.strip())

    return {
        "text": " ".join(full_text),
        "language": info.language,
        "confidence": info.language_probability,
        "segments": text_segments,
        "duration_ms": int(info.duration * 1000),
    }

{
    "text": "你好，世界",
    "voice": "zh-CN-XiaoxiaoNeural",
    "rate": "+0%",
    "pitch": "+0Hz",
    "format": "mp3"
}

{
    "audio_base64": "//NkxAAAAAAA...",
    "duration_ms": 1500,
    "processing_time_ms": 250,
    "cached": false
}

async def synthesize(self, request: TTSRequest) -> TTSResponse:
    """
    文本转语音（批量模式）
    """
    start_time = time.time()

    # 1. 检查缓存
    voice = request.voice or "zh-CN-XiaoxiaoNeural"
    rate = request.rate or "+0%"
    pitch = request.pitch or "+0Hz"
    format = request.format or "mp3"

    cached_audio_bytes = self.cache.get(
        text=request.text,
        voice=voice,
        rate=rate,
        pitch=pitch,
        format=format,
    )

    if cached_audio_bytes:
        logger.info("TTS cache hit")
        audio_base64 = base64.b64encode(cached_audio_bytes).decode("utf-8")
        return TTSResponse(
            audio_base64=audio_base64,
            duration_ms=0,
            processing_time_ms=(time.time() - start_time) * 1000,
            cached=True,
        )

    # 2. Edge TTS合成
    if self.provider == "edge":
        audio_data = await self._synthesize_with_edge(request)
    elif self.provider == "azure":
        audio_data = await self._synthesize_with_azure(request)
    else:
        raise ValueError(f"Unsupported TTS provider: {self.provider}")

    # 3. 存入缓存
    self.cache.set(
        text=request.text,
        voice=voice,
        rate=rate,
        pitch=pitch,
        format=format,
        audio_data=audio_data,
    )

    # 4. 编码为Base64
    audio_base64 = base64.b64encode(audio_data).decode("utf-8")

    processing_time_ms = (time.time() - start_time) * 1000

    return TTSResponse(
        audio_base64=audio_base64,
        duration_ms=0,
        processing_time_ms=processing_time_ms,
        cached=False,
    )

async def _synthesize_with_edge(self, request: TTSRequest) -> bytes:
    """使用Edge TTS合成"""
    import edge_tts

    communicate = edge_tts.Communicate(
        text=request.text,
        voice=request.voice,
        rate=request.rate,
        pitch=request.pitch,
    )

    audio_chunks = []
    async for chunk in communicate.stream():
        if chunk["type"] == "audio":
            audio_chunks.append(chunk["data"])

    return b"".join(audio_chunks)

# 1. 配置消息（JSON）
{
    "model_size": "base",
    "language": "zh",
    "vad_enabled": true
}

# 2. 音频数据（Binary）
[binary audio data: PCM 16kHz 16bit mono]

# 3. 结束信号（JSON）
{
    "type": "end_stream"
}

# 1. 会话开始
{
    "type": "session_start",
    "model_size": "base",
    "language": "zh"
}

# 2. 语音开始
{
    "type": "speech_start",
    "timestamp": 1.5
}

# 3. 部分结果
{
    "type": "partial_result",
    "text": "你好",
    "is_final": false,
    "confidence": 0.8
}

# 4. 最终结果
{
    "type": "final_result",
    "text": "你好世界",
    "is_final": true,
    "confidence": 0.95
}

# 5. 语音结束
{
    "type": "speech_end",
    "timestamp": 3.2
}

# 6. 会话结束
{
    "type": "session_end",
    "total_duration": 5.0
}

@router.websocket("/api/v1/asr/recognize/stream")
async def websocket_asr_stream(websocket: WebSocket):
    """
    WebSocket流式ASR识别
    """
    await websocket.accept()
    logger.info("WebSocket connection established")

    try:
        # 1. 接收配置
        config_msg = await websocket.receive_json()
        model_size = config_msg.get("model_size", "base")
        language = config_msg.get("language", "zh")
        vad_enabled = config_msg.get("vad_enabled", True)

        # 2. 初始化流式ASR服务
        service = StreamingASRService(
            model_size=model_size,
            language=language,
            vad_enabled=vad_enabled,
        )

        # 3. 音频生成器
        async def audio_generator():
            """从WebSocket接收音频数据"""
            while True:
                try:
                    message = await websocket.receive()

                    if "bytes" in message:
                        # 接收到音频数据
                        yield message["bytes"]

                    elif "text" in message:
                        # 接收到控制命令
                        cmd = json.loads(message["text"])
                        if cmd.get("type") == "end_stream":
                            break

                except WebSocketDisconnect:
                    break

        # 4. 处理流式识别并返回结果
        async for result in service.process_stream(audio_generator()):
            try:
                await websocket.send_json(result)
            except WebSocketDisconnect:
                break

        logger.info("Streaming ASR session completed")

    except Exception as e:
        logger.error(f"Streaming ASR error: {e}", exc_info=True)
        try:
            await websocket.send_json({
                "type": "error",
                "error": str(e)
            })
        except:
            pass

    finally:
        await websocket.close()

# StreamingASRService实现
class StreamingASRService:
    async def process_stream(self, audio_generator):
        """
        处理流式音频并返回识别结果
        """
        # 音频缓冲区
        audio_buffer = []
        buffer_duration = 0.0
        chunk_duration = 5.0  # 每5秒处理一次

        # 发送会话开始
        yield {
            "type": "session_start",
            "model_size": self.model_size,
            "language": self.language,
        }

        async for audio_chunk in audio_generator:
            # 累积音频块
            audio_buffer.append(audio_chunk)
            buffer_duration += len(audio_chunk) / (16000 * 2)  # 16kHz, 16bit

            # 达到5秒后处理
            if buffer_duration >= chunk_duration:
                # 合并音频
                audio_data = b"".join(audio_buffer)

                # VAD检测
                if self.vad_enabled:
                    has_speech = await self._detect_speech(audio_data)
                    if not has_speech:
                        # 无语音，清空缓冲区
                        audio_buffer = []
                        buffer_duration = 0.0
                        continue

                # Whisper识别
                result = await self._transcribe(audio_data)

                # 返回部分结果
                yield {
                    "type": "partial_result",
                    "text": result["text"],
                    "is_final": False,
                    "confidence": result.get("confidence", 0.0),
                }

                # 清空缓冲区
                audio_buffer = []
                buffer_duration = 0.0

        # 处理剩余音频
        if audio_buffer:
            audio_data = b"".join(audio_buffer)
            result = await self._transcribe(audio_data)

            yield {
                "type": "final_result",
                "text": result["text"],
                "is_final": True,
                "confidence": result.get("confidence", 0.0),
            }

        # 发送会话结束
        yield {
            "type": "session_end",
            "total_duration": buffer_duration,
        }

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant WS as WebSocket Server
    participant Service as StreamingASRService
    participant VAD as VADService
    participant Whisper as Whisper Model

    Client->>WS: WebSocket握手
    WS-->>Client: 连接建立

    Client->>WS: 配置消息 {"model_size":"base", "language":"zh"}
    WS->>Service: 初始化StreamingASRService(config)
    Service-->>WS: 初始化完成
    WS-->>Client: {"type":"session_start"}

    loop 流式音频传输
        Client->>WS: 音频块（binary）
        WS->>Service: 累积到buffer
        Service->>Service: buffer_duration += chunk_duration

        alt buffer >= 5秒
            Service->>VAD: detect_speech(audio_buffer)
            VAD->>VAD: Silero VAD检测
            VAD-->>Service: has_speech=true

            alt 有语音
                Service->>Whisper: transcribe(audio_buffer)
                Whisper->>Whisper: 推理识别
                Whisper-->>Service: {"text":"你好世界", "confidence":0.9}

                Service-->>WS: {"type":"partial_result", "text":"你好世界"}
                WS-->>Client: partial_result

                Service->>Service: 清空buffer
            else 无语音
                Service->>Service: 清空buffer（跳过识别）
            end
        end
    end

    Client->>WS: {"type":"end_stream"}

    alt buffer有剩余
        Service->>Whisper: transcribe(remaining_buffer)
        Whisper-->>Service: final_result
        Service-->>WS: {"type":"final_result"}
        WS-->>Client: final_result
    end

    Service-->>WS: {"type":"session_end"}
    WS-->>Client: session_end
    WS-->>Client: WebSocket关闭

# 服务配置
HOST=0.0.0.0
PORT=8004
WORKERS=4

# ASR配置
ASR_PROVIDER=whisper  # whisper/azure
WHISPER_MODEL=base    # tiny/base/small/medium/large
WHISPER_DEVICE=cuda   # cuda/cpu
WHISPER_COMPUTE_TYPE=int8  # int8/float16/float32

# TTS配置
TTS_PROVIDER=edge     # edge/azure
TTS_VOICE=zh-CN-XiaoxiaoNeural
TTS_RATE=+0%
TTS_PITCH=+0Hz

# VAD配置
VAD_MODEL=silero_vad_v4
VAD_SAMPLE_RATE=16000
VAD_THRESHOLD=0.5

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
TTS_CACHE_TTL=604800  # 7天

# Azure Speech配置（可选）
AZURE_SPEECH_KEY=your_key
AZURE_SPEECH_REGION=eastasia

# voice-engine.yaml
service:
  name: voice-engine
  version: 1.0.0

server:
  host: 0.0.0.0
  port: 8004
  workers: 4

asr:
  provider: whisper
  whisper:
    model: base
    device: cuda
    compute_type: int8
    download_root: ./models

  azure:
    enabled: false
    key: ${AZURE_SPEECH_KEY}
    region: eastasia

tts:
  provider: edge
  edge:
    voice: zh-CN-XiaoxiaoNeural
    rate: +0%
    pitch: +0Hz

  azure:
    enabled: false
    key: ${AZURE_SPEECH_KEY}
    region: eastasia

  cache:
    enabled: true
    backend: redis
    ttl: 604800 # 7天
    max_size_mb: 1000

vad:
  model: silero_vad_v4
  sample_rate: 16000
  threshold: 0.5
  mode: 3 # aggressive

redis:
  host: ${REDIS_HOST:localhost}
  port: 6379
  db: 0
  password: ${REDIS_PASSWORD}
  max_connections: 50

streaming:
  asr:
    buffer_duration_sec: 5.0
    chunk_duration_ms: 300
    max_buffer_duration_sec: 30.0

  websocket:
    max_connections: 100
    connection_timeout_sec: 1800
    ping_interval_sec: 30