feat(web): FastAPI 后端 + Streamlit 前端

- FastAPI: /api/process, /api/stream (WebSocket), /api/scenes, /api/models, /api/health
- Streamlit: 音频上传+录音, 原始转录vs纠正对比, 实体/意图/行动项展示
- 启动脚本: python web/run.py 一键启动

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip install *)",
+      "Bash(pip3 install *)",
+      "Bash(uv --version)",
+      "Bash(uv pip *)"
+    ]
+  }
+}

README.md

@@ -71,6 +71,24 @@ print(result.recovery.corrected_text)
 print(result.recovery.intent)
 ```
 
+### Web 界面
+
+```bash
+# 启动 FastAPI + Streamlit
+python web/run.py
+
+# 或分别启动
+uvicorn web.api:app --reload --port 8000   # API: http://localhost:8000/docs
+streamlit run web/app.py                     # UI: http://localhost:8501
+```
+
+**API 端点**:
+- `POST /api/process` — 上传音频处理
+- `WS /api/stream` — WebSocket 实时音频流
+- `GET /api/scenes` — 场景列表
+- `GET /api/models` — 可用模型
+- `GET /api/health` — 健康检查
+
 ## 技术栈
 
 | 组件 | 技术 |
@@ -93,6 +111,10 @@ speechbridge/
 │   ├── config.py       # 配置管理
 │   ├── models.py       # 数据模型
 │   └── pipeline.py     # 主管线
+├── web/
+│   ├── api.py          # FastAPI 后端
+│   ├── app.py          # Streamlit 前端
+│   └── run.py          # 启动脚本
 ├── cli.py              # 命令行入口
 ├── tests/              # 测试
 └── examples/           # 示例

web/api.py

@@ -0,0 +1,236 @@
+"""FastAPI 后端"""
+
+from __future__ import annotations
+
+import logging
+import tempfile
+from pathlib import Path
+
+from fastapi import FastAPI, File, HTTPException, Query, UploadFile, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+
+from src.speechbridge.config import PipelineConfig
+from src.speechbridge.models import OutputFormat, Scene
+from src.speechbridge.pipeline import SpeechBridgePipeline
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+app = FastAPI(
+    title="SpeechBridge API",
+    description="智能语义恢复系统 — 理解用户想表达什么",
+    version="0.1.0",
+)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# 全局管线实例
+_pipeline: SpeechBridgePipeline | None = None
+
+
+def get_pipeline() -> SpeechBridgePipeline:
+    global _pipeline
+    if _pipeline is None:
+        _pipeline = SpeechBridgePipeline(PipelineConfig.from_env())
+    return _pipeline
+
+
+@app.get("/")
+async def root():
+    return {"name": "SpeechBridge", "version": "0.1.0", "status": "running"}
+
+
+@app.get("/api/scenes")
+async def list_scenes():
+    """获取支持的场景列表"""
+    return {
+        "scenes": [
+            {"value": "general", "label": "通用", "description": "通用语义恢复"},
+            {"value": "meeting", "label": "会议", "description": "提取行动项和决策"},
+            {"value": "education", "label": "教育", "description": "课堂讨论和提问理解"},
+            {"value": "medical", "label": "医疗", "description": "症状和医疗术语提取"},
+            {"value": "accessibility", "label": "无障碍", "description": "语言障碍用户专项处理"},
+        ]
+    }
+
+
+@app.get("/api/models")
+async def list_models():
+    """获取可用模型信息"""
+    return {
+        "asr_models": ["tiny", "base", "small", "medium", "large-v3-turbo"],
+        "llm_providers": ["openai", "anthropic", "ollama"],
+        "tts_voices": [
+            "en-US-AriaNeural",
+            "en-US-GuyNeural",
+            "en-GB-SoniaNeural",
+            "zh-CN-XiaoxiaoNeural",
+        ],
+    }
+
+
+@app.post("/api/process")
+async def process_audio(
+    file: UploadFile = File(...),
+    scene: str = Query("general", description="应用场景"),
+    output_format: str = Query("json", description="输出格式: text/json/tts"),
+    accessibility: bool = Query(False, description="语言障碍模式"),
+):
+    """
+    处理上传的音频文件.
+
+    - **file**: 音频文件 (WAV, MP3, M4A, FLAC, OGG)
+    - **scene**: 应用场景 (general/meeting/education/medical/accessibility)
+    - **output_format**: 输出格式 (text/json/tts)
+    - **accessibility**: 是否启用语言障碍模式
+    """
+    # 验证场景
+    try:
+        scene_enum = Scene(scene)
+    except ValueError:
+        raise HTTPException(400, f"不支持的场景: {scene}")
+
+    try:
+        output_enum = OutputFormat(output_format)
+    except ValueError:
+        raise HTTPException(400, f"不支持的输出格式: {output_format}")
+
+    # 验证文件类型
+    allowed_types = {"audio/wav", "audio/x-wav", "audio/mpeg", "audio/mp3",
+                     "audio/m4a", "audio/flac", "audio/ogg", "audio/webm",
+                     "application/octet-stream"}
+    if file.content_type and file.content_type not in allowed_types:
+        # 允许 application/octet-stream 作为 fallback
+        pass
+
+    # 读取文件
+    content = await file.read()
+    if len(content) == 0:
+        raise HTTPException(400, "文件为空")
+
+    # 处理
+    pipeline = get_pipeline()
+    if accessibility:
+        pipeline.config.accessibility.enabled = True
+
+    try:
+        result = pipeline.process(
+            content,
+            filename=file.filename,
+            scene=scene_enum,
+            output_format=output_enum,
+        )
+    except Exception as e:
+        logger.error(f"处理失败: {e}", exc_info=True)
+        raise HTTPException(500, f"处理失败: {str(e)}")
+
+    # 返回结果
+    if output_format == "tts" and result.output_audio_path:
+        return FileResponse(
+            result.output_audio_path,
+            media_type="audio/mpeg",
+            filename="speechbridge_output.mp3",
+        )
+
+    return JSONResponse({
+        "asr": {
+            "text": result.asr.text,
+            "confidence": result.asr.segment_confidence,
+            "language": result.asr.language,
+            "duration": result.asr.duration,
+        },
+        "recovery": {
+            "original_text": result.recovery.original_text,
+            "corrected_text": result.recovery.corrected_text,
+            "intent": result.recovery.intent,
+            "entities": [
+                {"name": e.name, "type": e.type, "value": e.value}
+                for e in result.recovery.entities
+            ],
+            "actions": result.recovery.actions,
+            "corrections": [
+                {"original": c.original, "corrected": c.corrected, "reason": c.reason}
+                for c in result.recovery.corrections
+            ],
+            "confidence": result.recovery.confidence,
+            "processing_time": result.recovery.processing_time,
+        },
+        "total_time": result.total_time,
+    })
+
+
+@app.websocket("/api/stream")
+async def stream_audio(websocket: WebSocket):
+    """
+    WebSocket 实时音频流处理.
+
+    客户端发送音频数据块, 服务端返回识别和恢复结果.
+    消息协议:
+    - 客户端发送二进制帧: 音频数据 (16kHz mono float32)
+    - 客户端发送文本帧: JSON 配置 {"scene": "general", "accessibility": false}
+    - 服务端返回文本帧: JSON 结果
+    """
+    await websocket.accept()
+    logger.info("WebSocket 连接已建立")
+
+    scene = Scene.GENERAL
+    accessibility = False
+    audio_chunks = []
+
+    try:
+        while True:
+            message = await websocket.receive()
+
+            if "text" in message:
+                # 配置消息
+                import json
+                try:
+                    config = json.loads(message["text"])
+                    scene = Scene(config.get("scene", "general"))
+                    accessibility = config.get("accessibility", False)
+
+                    # 如果收到 finalize 信号, 处理累积的音频
+                    if config.get("finalize") and audio_chunks:
+                        pipeline = get_pipeline()
+                        if accessibility:
+                            pipeline.config.accessibility.enabled = True
+
+                        result = pipeline.process_stream(
+                            audio_chunks, scene=scene, output_format=OutputFormat.JSON
+                        )
+                        await websocket.send_text(result.output_text)
+                        audio_chunks = []
+
+                except (json.JSONDecodeError, ValueError) as e:
+                    await websocket.send_text(json.dumps({"error": str(e)}))
+
+            elif "bytes" in message:
+                # 音频数据
+                audio_chunks.append(message["bytes"])
+
+    except WebSocketDisconnect:
+        logger.info("WebSocket 连接已断开")
+    except Exception as e:
+        logger.error(f"WebSocket 错误: {e}", exc_info=True)
+        try:
+            await websocket.close()
+        except Exception:
+            pass
+
+
+@app.get("/api/health")
+async def health():
+    """健康检查"""
+    pipeline = get_pipeline()
+    return {
+        "status": "healthy",
+        "asr_loaded": pipeline.asr.is_loaded(),
+    }

web/app.py

@@ -0,0 +1,194 @@
+"""Streamlit 前端"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+import streamlit as st
+
+from src.speechbridge.config import PipelineConfig
+from src.speechbridge.models import OutputFormat, Scene
+from src.speechbridge.pipeline import SpeechBridgePipeline
+
+
+@st.cache_resource
+def load_pipeline():
+    """加载管线 (缓存)"""
+    config = PipelineConfig.from_env()
+    return SpeechBridgePipeline(config)
+
+
+def main():
+    st.set_page_config(
+        page_title="SpeechBridge",
+        page_icon="🌉",
+        layout="wide",
+    )
+
+    st.title("🌉 SpeechBridge")
+    st.caption("智能语义恢复系统 — 理解你想表达什么，而不仅仅是识别你说了什么")
+
+    # 侧边栏配置
+    with st.sidebar:
+        st.header("⚙️ 配置")
+
+        scene = st.selectbox(
+            "应用场景",
+            options=[s.value for s in Scene],
+            format_func={
+                "general": "🌐 通用",
+                "meeting": "🏢 会议",
+                "education": "📚 教育",
+                "medical": "🏥 医疗",
+                "accessibility": "♿ 无障碍",
+            }.get,
+            index=0,
+        )
+
+        accessibility = st.toggle("语言障碍模式", value=False)
+
+        st.divider()
+
+        output_format = st.radio(
+            "输出格式",
+            options=["text", "json"],
+            index=0,
+        )
+
+        st.divider()
+
+        st.markdown("### 📖 使用说明")
+        st.markdown("""
+        1. 上传音频文件或录制语音
+        2. 选择应用场景
+        3. 查看语义恢复结果
+
+        **支持格式**: WAV, MP3, M4A, FLAC, OGG
+        """)
+
+    # 主区域: 两列布局
+    col_input, col_output = st.columns(2)
+
+    with col_input:
+        st.header("🎤 输入")
+
+        # 输入方式选择
+        input_method = st.radio(
+            "输入方式",
+            options=["upload", "record"],
+            format_func={"upload": "📁 上传文件", "record": "🎙️ 实时录音"}.get,
+            horizontal=True,
+        )
+
+        audio_data = None
+        filename = None
+
+        if input_method == "upload":
+            uploaded = st.file_uploader(
+                "上传音频文件",
+                type=["wav", "mp3", "m4a", "flac", "ogg"],
+                help="支持 WAV, MP3, M4A, FLAC, OGG 格式",
+            )
+            if uploaded:
+                audio_data = uploaded.read()
+                filename = uploaded.name
+                st.audio(audio_data, format=f"audio/{uploaded.name.split('.')[-1]}")
+
+        else:
+            recorded = st.audio_input("录制语音")
+            if recorded:
+                audio_data = recorded.read()
+                filename = "recording.wav"
+                st.audio(audio_data, format="audio/wav")
+
+    with col_output:
+        st.header("📝 输出")
+
+        if audio_data and st.button("🚀 开始处理", type="primary", use_container_width=True):
+            pipeline = load_pipeline()
+
+            if accessibility:
+                pipeline.config.accessibility.enabled = True
+
+            scene_enum = Scene(scene)
+            output_enum = OutputFormat(output_format)
+
+            with st.spinner("处理中..."):
+                try:
+                    result = pipeline.process(
+                        audio_data,
+                        filename=filename,
+                        scene=scene_enum,
+                        output_format=output_enum,
+                    )
+                except Exception as e:
+                    st.error(f"处理失败: {e}")
+                    return
+
+            # 存储结果到 session state
+            st.session_state["result"] = result
+
+        # 显示结果
+        if "result" in st.session_state:
+            result = st.session_state["result"]
+
+            # 原始转录 vs 纠正文本
+            st.subheader("对比")
+            col_orig, col_fixed = st.columns(2)
+
+            with col_orig:
+                st.markdown("**原始转录**")
+                st.info(result.asr.text if result.asr.text else "(无)")
+
+            with col_fixed:
+                st.markdown("**纠正后文本**")
+                st.success(result.recovery.corrected_text if result.recovery.corrected_text else "(无)")
+
+            # 意图
+            if result.recovery.intent:
+                st.subheader("🎯 意图")
+                st.write(result.recovery.intent)
+
+            # 实体
+            if result.recovery.entities:
+                st.subheader("📦 提取的实体")
+                entity_data = [
+                    {"名称": e.name, "类型": e.type, "值": e.value}
+                    for e in result.recovery.entities
+                ]
+                st.dataframe(entity_data, use_container_width=True)
+
+            # 纠正详情
+            if result.recovery.corrections:
+                st.subheader("🔧 纠正详情")
+                for c in result.recovery.corrections:
+                    st.markdown(f'- "{c.original}" → "{c.corrected}" _{c.reason}_')
+
+            # 行动项
+            if result.recovery.actions:
+                st.subheader("📋 行动项")
+                for i, a in enumerate(result.recovery.actions, 1):
+                    st.markdown(f"{i}. {a}")
+
+            # 元信息
+            st.divider()
+            meta_cols = st.columns(4)
+            with meta_cols[0]:
+                st.metric("ASR 置信度", f"{result.asr.segment_confidence:.2f}")
+            with meta_cols[1]:
+                st.metric("恢复置信度", f"{result.recovery.confidence:.2f}")
+            with meta_cols[2]:
+                st.metric("语义恢复耗时", f"{result.recovery.processing_time:.2f}s")
+            with meta_cols[3]:
+                st.metric("总耗时", f"{result.total_time:.2f}s")
+
+            # JSON 原始数据
+            with st.expander("🔍 查看原始 JSON 数据"):
+                st.json(json.loads(result.output_text) if output_format == "json"
+                        else {"text": result.output_text})
+
+
+if __name__ == "__main__":
+    main()

web/run.py

@@ -0,0 +1,54 @@
+"""启动 Web 服务"""
+
+import subprocess
+import sys
+
+
+def main():
+    print("=" * 50)
+    print("SpeechBridge Web 服务")
+    print("=" * 50)
+    print()
+    print("启动中...")
+    print()
+    print("FastAPI 后端: http://localhost:8000")
+    print("API 文档:     http://localhost:8000/docs")
+    print("Streamlit:    http://localhost:8501")
+    print()
+    print("按 Ctrl+C 停止所有服务")
+    print("=" * 50)
+
+    processes = []
+
+    try:
+        # 启动 FastAPI
+        api_proc = subprocess.Popen(
+            [sys.executable, "-m", "uvicorn", "web.api:app", "--host", "0.0.0.0", "--port", "8000", "--reload"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+        )
+        processes.append(("FastAPI", api_proc))
+
+        # 启动 Streamlit
+        streamlit_proc = subprocess.Popen(
+            [sys.executable, "-m", "streamlit", "run", "web/app.py", "--server.port", "8501",
+             "--server.headless", "true"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+        )
+        processes.append(("Streamlit", streamlit_proc))
+
+        # 等待任一进程退出
+        for name, proc in processes:
+            proc.wait()
+
+    except KeyboardInterrupt:
+        print("\n停止服务...")
+        for name, proc in processes:
+            proc.terminate()
+            proc.wait()
+        print("已停止")
+
+
+if __name__ == "__main__":
+    main()