deploy: backend for appQQQ/ai-chatbot

FastAPI + LangGraph + Docling + BGE-M3 + ChromaDB.
Initial release from shuaiwang888/AI-Chatbot main branch.

.gitignore

@@ -0,0 +1,45 @@
+# HF Space build context .gitignore
+# 不要 push 本地开发数据 / venv / 缓存
+
+# Local data
+data/
+data/**
+*.db
+*.sqlite
+*.sqlite3
+*.parquet
+*.arrow
+*.bin
+*.safetensors
+*.gguf
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Env & secrets (Space 走 Secrets, 不走 .env)
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+
+# Node (backend 不用, 但防误传)
+node_modules/
+dist/
+*.log
+
+# IDE
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Tests (本项目走 GH Actions, Space 端不跑)
+tests/

Dockerfile

@@ -0,0 +1,64 @@
+# HuggingFace Spaces Docker image
+# python:3.12-slim 是 2026-06 推荐基础镜像
+FROM python:3.12-slim
+
+# HF Spaces 元数据
+LABEL org.opencontainers.image.title="ai-chatbot"
+LABEL org.opencontainers.image.description="Agentic multimodal RAG customer service"
+LABEL org.opencontainers.image.source="https://github.com/yourname/ai-chatbot"
+LABEL org.opencontainers.image.licenses="MIT"
+
+# 环境
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    DATA_DIR=/data \
+    HF_HOME=/data/.cache/huggingface \
+    TRANSFORMERS_CACHE=/data/.cache/huggingface \
+    TOKENIZERS_PARALLELISM=false
+
+# 系统依赖 (Poppler for PDF, GL libs for OpenCV/PaddleOCR)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        gcc \
+        g++ \
+        libgl1 \
+        libglib2.0-0 \
+        poppler-utils \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# 工作目录
+WORKDIR /app
+
+# 先复制 requirements 利用 Docker 层缓存
+COPY requirements.txt .
+
+# 安装 Python 依赖
+# 单独 install FlagEmbedding 比较慢, 但因为在 requirements.txt 里只装一次
+RUN pip install -r requirements.txt
+
+# 可选: 预热模型 (避免 Space 启动超时). 如果镜像太大, 可注释掉, 运行时再下载
+# RUN python -c "from FlagEmbedding import BGEM3FlagModel, FlagReranker; \
+#     BGEM3FlagModel('BAAI/bge-m3', use_fp16=True); \
+#     FlagReranker('BAAI/bge-reranker-v2-m3')" \
+#     || echo "Model pre-warm skipped (will download on first startup)"
+
+# 复制应用代码
+COPY app ./app
+COPY pyproject.toml ./pyproject.toml
+
+# 数据目录 (HF Space 持久卷挂载点)
+RUN mkdir -p /data/chroma /data/sqlite /data/uploads /data/.cache/huggingface
+
+# 健康检查
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:7860/api/v1/healthz || exit 1
+
+# 暴露端口 (HF Spaces 约定 7860)
+EXPOSE 7860
+
+# 启动命令
+# --workers 1: 避免 BGE-M3 / ChromaDB 在多 worker 下重复加载模型
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1", "--proxy-headers", "--forwarded-allow-ips", "*"]

README.md

@@ -1,11 +1,33 @@
 ---
-title: Ai Chatbot
-emoji: 💻
-colorFrom: gray
-colorTo: indigo
+title: AI Chatbot
+emoji: "\U0001F916"
+colorFrom: blue
+colorTo: purple
 sdk: docker
-pinned: false
-short_description: 基于多模态文档 (PDF / Word / 图片) 的私人智能客服，支持多轮对话、引用源、工具调用 (Agent 模式)
+pinned: true
+license: mit
+short_description: Agentic multimodal RAG customer service (private)
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# AI Chatbot Backend
+
+Agentic multimodal RAG customer service backend.
+
+- FastAPI + LangGraph (StateGraph)
+- Docling (PDF/Word/Image) + BGE-M3 + ChromaDB
+- MiniMax-M3 (default) / switchable to OpenAI / Anthropic / Qwen
+- Persistent via HF Dataset repo (free tier disk is ephemeral)
+
+## Endpoints
+
+- `GET  /api/v1/healthz` — liveness
+- `GET  /api/v1/readyz`  — readiness (Chroma + LLM reachable)
+- `POST /api/v1/chat` — non-streaming chat
+- `POST /api/v1/chat/stream` — SSE stream (astream_events v2)
+- `POST /api/v1/documents/upload` — upload + ingest
+- `GET  /api/v1/documents` — list
+- `DELETE /api/v1/documents/{id}` — remove
+- `GET  /api/v1/sessions` — list sessions
+- `DELETE /api/v1/sessions/{id}` — clear session
+
+See [PLAN.md](../PLAN.md) for full design.

app/__init__.py

@@ -0,0 +1,46 @@
+"""ai-chatbot backend application."""
+__version__ = "0.1.0"
+
+# Monkey patch transformers to bypass torch.load safety check on old PyTorch versions (macOS x86_64)
+try:
+    import transformers.utils.import_utils
+    transformers.utils.import_utils.check_torch_load_is_safe = lambda *args, **kwargs: None
+    transformers.utils.import_utils.is_torch_mps_available = lambda *args, **kwargs: False
+except ImportError:
+    pass
+
+try:
+    import transformers.modeling_utils
+    transformers.modeling_utils.check_torch_load_is_safe = lambda *args, **kwargs: None
+except ImportError:
+    pass
+
+# Force CPU device for PyTorch MPS on Intel Macs to prevent NotImplementedError
+try:
+    import torch
+    torch.backends.mps.is_available = lambda: False
+    torch.backends.mps.is_built = lambda: False
+    if hasattr(torch, "mps"):
+        torch.mps.is_available = lambda: False
+except ImportError:
+    pass
+
+# Force CPU device for accelerate to avoid MPS auto mapping
+try:
+    import accelerate.utils
+    accelerate.utils.is_mps_available = lambda *args, **kwargs: False
+except ImportError:
+    pass
+
+try:
+    import accelerate.utils.imports
+    accelerate.utils.imports.is_mps_available = lambda *args, **kwargs: False
+except ImportError:
+    pass
+
+# Force CPU device for Docling to prevent early MPS detection during import
+try:
+    import docling.utils.accelerator_utils
+    docling.utils.accelerator_utils.decide_device = lambda *args, **kwargs: "cpu"
+except ImportError:
+    pass

app/agents/__init__.py

@@ -0,0 +1 @@
+"""LangGraph agent (阶段 3 接入). 阶段 1 留空壳."""

app/agents/graph.py

@@ -0,0 +1,124 @@
+"""LangGraph StateGraph 装配 + 编译.
+
+设计: 图只负责"检索循环" (route → query_rewrite → retrieve → rerank → evaluate).
+answer 流式生成由 chat 端点直接驱动 (answer_node_stream + asyncio.Queue),
+这样 SSE token 流不依赖 astream_events 的复杂性.
+
+流程图:
+
+    START
+      │
+      ▼
+   route ─── direct ───────────────────────────────► END
+      │
+      ▼
+   query_rewrite ──► retrieve ──► rerank ──► evaluate
+                                                   │
+                       ┌──── (needs_more, iter<max) ───┐
+                       │                              │
+                       └──── (relevant/irrelevant/max) ┘
+                              │
+                              ▼
+                             END
+"""
+from __future__ import annotations
+
+import logging
+
+from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+from langgraph.graph import END, START, StateGraph
+
+from app.agents.nodes import (
+    evaluate_node,
+    query_rewrite_node,
+    rerank_node,
+    retrieve_node,
+    route_node,
+)
+from app.agents.state import AgentState
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+# ========== 边决策 ==========
+def _after_route(state: AgentState) -> str:
+    decision = state.get("route_decision", "retrieve")
+    if decision == "direct":
+        return END
+    return "query_rewrite"
+
+
+def _after_evaluate(state: AgentState) -> str:
+    """evaluate 后: needs_more + iter<max -> 回 retrieve; 否则 END."""
+    if state.get("needs_more_retrieval", False):
+        return "query_rewrite"
+    return END
+
+
+# ========== 编译 ==========
+def _build_graph() -> StateGraph:
+    g = StateGraph(AgentState)
+
+    g.add_node("route", route_node)
+    g.add_node("query_rewrite", query_rewrite_node)
+    g.add_node("retrieve", retrieve_node)
+    g.add_node("rerank", rerank_node)
+    g.add_node("evaluate", evaluate_node)
+
+    g.add_edge(START, "route")
+    g.add_conditional_edges(
+        "route", _after_route,
+        {END: END, "query_rewrite": "query_rewrite"},
+    )
+    g.add_edge("query_rewrite", "retrieve")
+    g.add_edge("retrieve", "rerank")
+    g.add_edge("rerank", "evaluate")
+    g.add_conditional_edges(
+        "evaluate", _after_evaluate,
+        {END: END, "query_rewrite": "query_rewrite"},
+    )
+
+    return g
+
+
+# ========== 编译产物 (带 checkpointer) ==========
+_compiled = None
+_saver_cm = None
+_compiled_loop = None
+
+
+async def get_compiled_graph():
+    """懒加载 + 单例 (按 event loop 隔离)."""
+    global _compiled, _saver_cm, _compiled_loop
+    import asyncio
+    current_loop = asyncio.get_running_loop()
+
+    if _compiled is not None and _compiled_loop is current_loop:
+        return _compiled
+
+    if _compiled is not None:
+        await close_checkpointer()
+
+    g = _build_graph()
+    _saver_cm = AsyncSqliteSaver.from_conn_string(str(settings.langgraph_db_path))
+    saver = await _saver_cm.__aenter__()
+    _compiled = g.compile(checkpointer=saver)
+    _compiled_loop = current_loop
+    logger.info(
+        "LangGraph compiled with AsyncSqliteSaver at %s",
+        settings.langgraph_db_path,
+    )
+    return _compiled
+
+
+async def close_checkpointer() -> None:
+    global _compiled, _saver_cm, _compiled_loop
+    _compiled = None
+    _compiled_loop = None
+    if _saver_cm is not None:
+        try:
+            await _saver_cm.__aexit__(None, None, None)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("AsyncSqliteSaver close failed: %s", e)
+        _saver_cm = None

app/agents/nodes.py

@@ -0,0 +1,480 @@
+"""LangGraph 节点实现.
+
+每个 node 接收 AgentState, 返回部分更新的 dict.
+节点间通过 state 自动传递, 不直接耦合.
+
+设计要点:
+- 节点只做一件事, 容易测试
+- LLM 调用统一走工厂, 走 LLM cache
+- 异常不抛, 写入 state['error'], 让图走 fallback 边
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+from typing import Any
+
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
+
+from app.agents.prompts import (
+    ANSWER_PROMPT,
+    CRAG_EVAL_PROMPT,
+    MULTI_STEP_PROMPT,
+    QUERY_REWRITE_PROMPT,
+    ROUTE_PROMPT,
+)
+from app.agents.state import AgentState
+from app.agents.tools import TOOL_SCHEMAS, execute_tool
+from app.config import settings
+from app.llm.base import LLMMessage
+from app.llm.factory import get_llm
+from app.services.embedding import get_embedder
+from app.services.llm_cache import CachedAnswer, lookup as cache_lookup, store as cache_store
+from app.services.reranker import get_reranker_service
+from app.services.vector_store import RetrievalHit, hybrid_query
+
+logger = logging.getLogger(__name__)
+
+
+# ========== 工具: 取最近用户消息文本 ==========
+def _last_user_query(state: AgentState) -> str:
+    for m in reversed(list(state.get("messages") or [])):
+        if hasattr(m, "type") and m.type == "human":
+            return m.content if isinstance(m.content, str) else str(m.content)
+        if isinstance(m, dict) and m.get("role") == "user":
+            return m.get("content", "")
+    return ""
+
+
+def _safe_json(text: str) -> dict | None:
+    """尽量从 LLM 输出中抠 JSON. 失败返回 None."""
+    if not text:
+        return None
+    # 尝试直接 parse
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    # 抠 ```json ... ```
+    m = re.search(r"```(?:json)?\s*(\{.*?\}|\[.*?\])\s*```", text, re.DOTALL)
+    if m:
+        try:
+            return json.loads(m.group(1))
+        except json.JSONDecodeError:
+            pass
+    # 抠第一个 { ... }
+    m = re.search(r"\{.*\}", text, re.DOTALL)
+    if m:
+        try:
+            return json.loads(m.group(0))
+        except json.JSONDecodeError:
+            pass
+    return None
+
+
+# ========== Node 1: route ==========
+async def route_node(state: AgentState) -> dict[str, Any]:
+    """判断 query 走向: direct / retrieve / multi_step."""
+    started = time.time()
+    query = _last_user_query(state)
+    if not query:
+        return {"route_decision": "retrieve"}
+
+    # 启发式快路 (避免每次都 LLM 调用)
+    ql = query.strip().lower()
+    if len(ql) <= 12 and any(g in ql for g in (
+        "你好", "您好", "hi", "hello", "hey", "你是谁", "what's up", "how are you",
+        "thanks", "thank you", "谢谢", "再见", "bye",
+    )):
+        return {"route_decision": "direct", "query_rewritten": query}
+
+    try:
+        llm = get_llm()
+        resp = await llm.chat(
+            messages=[
+                LLMMessage(role="system", content=ROUTE_PROMPT),
+                LLMMessage(role="user", content=query),
+            ],
+            temperature=0.0,
+            max_tokens=80,
+        )
+        data = _safe_json(resp.content or "")
+        decision = data.get("route", "retrieve") if data else "retrieve"
+        if decision not in ("direct", "retrieve", "multi_step"):
+            decision = "retrieve"
+        logger.debug("route: %s (%sms) reason=%s", decision, int((time.time() - started) * 1000),
+                     (data or {}).get("reason", ""))
+        return {"route_decision": decision, "query_rewritten": query}
+    except Exception as e:  # noqa: BLE001
+        logger.warning("route_node failed: %s, default to retrieve", e)
+        return {"route_decision": "retrieve", "query_rewritten": query}
+
+
+# ========== Node 2: query_rewrite ==========
+async def query_rewrite_node(state: AgentState) -> dict[str, Any]:
+    """对 query 改写, 提升召回. multi_step 时拆子问题."""
+    started = time.time()
+    query = state.get("query_rewritten") or _last_user_query(state)
+    if state.get("route_decision") == "direct":
+        return {"query_rewritten": query, "plan": []}
+
+    try:
+        llm = get_llm()
+        if state.get("route_decision") == "multi_step":
+            resp = await llm.chat(
+                messages=[
+                    LLMMessage(role="system", content=MULTI_STEP_PROMPT),
+                    LLMMessage(role="user", content=query),
+                ],
+                temperature=0.2,
+                max_tokens=200,
+            )
+            data = _safe_json(resp.content or "")
+            steps = (data or {}).get("steps", [query])
+            if not isinstance(steps, list) or not steps:
+                steps = [query]
+            return {"query_rewritten": steps[0], "plan": steps}
+
+        resp = await llm.chat(
+            messages=[
+                LLMMessage(role="system", content=QUERY_REWRITE_PROMPT.format(query=query)),
+            ],
+            temperature=0.3,
+            max_tokens=200,
+        )
+        data = _safe_json(resp.content or "")
+        rewrites = (data or {}).get("rewrites", [])
+        if not isinstance(rewrites, list) or not rewrites:
+            rewrites = [query]
+        # 拼接为最终检索串
+        merged = " | ".join([query] + list(rewrites[:2]))
+        logger.debug("query_rewrite: %d variants, %dms", len(rewrites), int((time.time() - started) * 1000))
+        return {"query_rewritten": merged, "plan": []}
+    except Exception as e:  # noqa: BLE001
+        logger.warning("query_rewrite failed: %s", e)
+        return {"query_rewritten": query, "plan": []}
+
+
+# ========== Node 3: retrieve ==========
+async def retrieve_node(state: AgentState) -> dict[str, Any]:
+    """混合检索 top-K."""
+    started = time.time()
+    query = state.get("query_rewritten") or _last_user_query(state)
+    if not query:
+        return {"retrieved": [], "retrieved_doc_ids": []}
+
+    embedder = get_embedder()
+    out = await embedder.encode_query(query)
+    dense = out["dense"]
+    # dense shape: (1, 1024) or (1024,) depending on encode return
+    if dense.ndim == 2:
+        dense_vec = dense[0]
+    else:
+        dense_vec = dense
+    sparse = out.get("sparse", [{}])[0] if out.get("sparse") else None
+    colbert = out.get("colbert", [None])[0] if out.get("colbert") else None
+
+    # multi_step: 每步独立检索再合并
+    plan = state.get("plan") or []
+    all_hits: list[RetrievalHit] = []
+    seen: set[str] = set()
+    queries_to_run = plan if plan else [query]
+    for q in queries_to_run:
+        if q == query and all_hits:
+            continue  # 主 query 已跑过
+        if q != query:
+            sub_out = await embedder.encode_query(q)
+            sub_dense = sub_out["dense"][0] if sub_out["dense"].ndim == 2 else sub_out["dense"]
+            sub_sparse = sub_out.get("sparse", [{}])[0] if sub_out.get("sparse") else None
+            sub_colbert = sub_out.get("colbert", [None])[0] if sub_out.get("colbert") else None
+            hits = hybrid_query(
+                query_emb=sub_dense,
+                query_sparse=sub_sparse,
+                query_colbert_emb=sub_colbert,
+                k=settings.rerank_top_n * 4,
+            )
+        else:
+            hits = hybrid_query(
+                query_emb=dense_vec,
+                query_sparse=sparse,
+                query_colbert_emb=colbert,
+                k=settings.rerank_top_n * 4,
+            )
+        for h in hits:
+            if h.chunk_id not in seen:
+                seen.add(h.chunk_id)
+                all_hits.append(h)
+
+    # 按 score 截前 N
+    all_hits.sort(key=lambda h: h.score, reverse=True)
+    all_hits = all_hits[: settings.rerank_top_n * 4]
+
+    doc_ids = list({h.doc_id for h in all_hits if h.doc_id})
+    logger.debug("retrieve: %d hits, %d docs, %dms",
+                 len(all_hits), len(doc_ids), int((time.time() - started) * 1000))
+    return {"retrieved": all_hits, "retrieved_doc_ids": doc_ids}
+
+
+# ========== Node 4: rerank ==========
+async def rerank_node(state: AgentState) -> dict[str, Any]:
+    """BGE-reranker 精排 top-N + 产出引用."""
+    started = time.time()
+    hits = state.get("retrieved") or []
+    query = state.get("query_rewritten") or _last_user_query(state)
+    if not hits:
+        return {"reranked": [], "citations": [], "relevance_score": 0.0, "relevance_verdict": "irrelevant"}
+
+    reranker = get_reranker_service()
+    reranked = await reranker.rerank(query, hits, top_n=settings.rerank_top_n)
+
+    # 构造引用 (前 5 个, 按 rerank 分数)
+    citations: list[dict[str, Any]] = []
+    for i, h in enumerate(reranked):
+        doc = _doc_meta_brief(h.doc_id)
+        citations.append({
+            "doc_id": h.doc_id,
+            "filename": doc.get("filename", "未知"),
+            "page": h.page_no,
+            "heading": h.heading,
+            "snippet": (h.text or "")[:240],
+            "score": round(h.rerank_score, 4),
+            "rank": i + 1,
+        })
+
+    top_score = reranked[0].rerank_score if reranked else 0.0
+    if top_score >= settings.crag_relevance_threshold:
+        verdict = "relevant"
+    elif top_score < 0.3:
+        verdict = "irrelevant"
+    else:
+        verdict = "ambiguous"
+
+    logger.debug("rerank: top=%.3f verdict=%s %dms", top_score, verdict, int((time.time() - started) * 1000))
+    return {
+        "reranked": reranked,
+        "citations": citations,
+        "relevance_score": top_score,
+        "relevance_verdict": verdict,
+    }
+
+
+def _doc_meta_brief(doc_id: str) -> dict[str, Any]:
+    try:
+        from app.models import db
+        d = db.doc_get(doc_id)
+        return d or {}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+# ========== Node 5: answer (流式 LLM 调用) ==========
+async def answer_node_stream(
+    state: AgentState,
+    on_token: Any = None,  # async callable(content: str) -> None
+    on_citation: Any = None,
+    on_thinking: Any = None,
+) -> dict[str, Any]:
+    """生成最终答案. 通过 on_token 回调逐 token 推送.
+
+    流程:
+    1. 拼装 context (从 reranked hits)
+    2. 查 LLM 缓存
+    3. 命中: 回放 tokens
+    4. 未命中: 调 LLM 流式 + 缓存结果
+    """
+    query = state.get("query_rewritten") or _last_user_query(state)
+    reranked = state.get("reranked") or []
+    locale = state.get("locale", "zh")
+
+    # 拼 context
+    if reranked:
+        ctx_lines: list[str] = []
+        for i, h in enumerate(reranked, 1):
+            tag = f"[{i}]"
+            prefix_bits = []
+            if h.heading:
+                prefix_bits.append(f"章节: {h.heading}")
+            if h.page_no:
+                prefix_bits.append(f"页码: {h.page_no}")
+            if h.context_prefix:
+                prefix_bits.append(f"上下文: {h.context_prefix}")
+            meta = " | ".join(prefix_bits)
+            ctx_lines.append(f"{tag} {('('+meta+')') if meta else ''}\n{h.text}")
+        context = "\n\n".join(ctx_lines)
+    else:
+        if on_thinking:
+            await on_thinking("未在知识库中找到相关文档, 直接基于通用知识回答。")
+        context = "(无相关文档)"
+
+    prompt = ANSWER_PROMPT.format(context=context, query=query, LOCALE=locale)
+    system_msg = "你是私人智能客服, 回答需基于 context 引用, 用对应 locale 回答。"
+
+    # 缓存 key
+    top_doc_ids = [c["doc_id"] for c in state.get("citations", [])]
+    cached = cache_lookup(query, top_doc_ids, 0.7)
+
+    started = time.time()
+    if cached is not None:
+        # 回放
+        if on_thinking:
+            await on_thinking("(cache hit, 跳过 LLM)")
+        for tok in cached.tokens:
+            if on_token:
+                await on_token(tok)
+        return {
+            "final_answer": cached.content,
+            "messages": [AIMessage(content=cached.content)],
+            "elapsed_ms": int((time.time() - started) * 1000),
+        }
+
+    # 实际 LLM 流式
+    llm = get_llm()
+    collected: list[str] = []
+    full_text = ""
+    try:
+        async for chunk in llm.stream_chat(
+            messages=[
+                LLMMessage(role="system", content=system_msg),
+                LLMMessage(role="user", content=prompt),
+            ],
+            temperature=0.7,
+            max_tokens=1200,
+        ):
+            if chunk.content:
+                collected.append(chunk.content)
+                full_text += chunk.content
+                if on_token:
+                    await on_token(chunk.content)
+    except Exception as e:  # noqa: BLE001
+        logger.exception("answer_node_stream failed")
+        err_msg = f"抱歉, 生成答案时出错: {e}"
+        if on_token:
+            await on_token(err_msg)
+        return {
+            "final_answer": err_msg,
+            "messages": [AIMessage(content=err_msg)],
+            "error": str(e),
+        }
+
+    # 缓存结果
+    cache_store(query, top_doc_ids, 0.7, CachedAnswer(
+        content=full_text,
+        citations=state.get("citations", []),
+        tool_calls=[],
+        tokens=collected,
+    ))
+
+    # 推引用 (在 answer 末尾)
+    if on_citation and state.get("citations"):
+        for c in state["citations"]:
+            await on_citation(c)
+
+    return {
+        "final_answer": full_text,
+        "messages": [AIMessage(content=full_text)],
+        "elapsed_ms": int((time.time() - started) * 1000),
+    }
+
+
+# ========== Node 6: evaluate (CRAG) ==========
+async def evaluate_node(state: AgentState) -> dict[str, Any]:
+    """CRAG 自校正判定.
+
+    阶段 1 (必走, 极快): 用 rerank top-1 score 做硬阈值判断
+    阶段 2 (仅模糊区间): LLM judge 二次判定, 决定是否回 retrieve
+    """
+    iteration = state.get("iteration", 0) + 1
+    score = state.get("relevance_score", 0.0)
+    verdict = state.get("relevance_verdict", "ambiguous")
+    max_iter = state.get("max_iterations", settings.crag_max_iterations)
+
+    # 阶段 1: rerank 分数硬阈值
+    if verdict == "relevant":
+        return {
+            "iteration": iteration,
+            "needs_more_retrieval": False,
+            "crag_finished": True,
+        }
+    if verdict == "irrelevant":
+        # 直接告知用户, 不再循环
+        return {
+            "iteration": iteration,
+            "needs_more_retrieval": False,
+            "crag_finished": True,
+        }
+
+    # 阶段 2: 模糊区间, 调 LLM judge (用便宜的 judge model)
+    if iteration >= max_iter:
+        # 超过上限, 收口
+        return {
+            "iteration": iteration,
+            "needs_more_retrieval": False,
+            "crag_finished": True,
+        }
+
+    try:
+        llm = get_llm()  # 用同 model (个人项目成本可接受)
+        query = state.get("query_rewritten") or _last_user_query(state)
+        reranked = state.get("reranked") or []
+        docs_summary = "\n".join(
+            f"[{i+1}] {h.heading or '无标题'}: {(h.text or '')[:120]}"
+            for i, h in enumerate(reranked[:5])
+        )
+        resp = await llm.chat(
+            messages=[
+                LLMMessage(role="system", content=CRAG_EVAL_PROMPT.format(
+                    query=query, n=len(reranked[:5]), docs_summary=docs_summary,
+                )),
+            ],
+            temperature=0.0,
+            max_tokens=120,
+        )
+        data = _safe_json(resp.content or "")
+        v = (data or {}).get("verdict", "sufficient")
+        needs = v == "insufficient" and iteration < max_iter
+        return {
+            "iteration": iteration,
+            "needs_more_retrieval": needs,
+            "crag_finished": not needs,
+        }
+    except Exception as e:  # noqa: BLE001
+        logger.warning("evaluate_node LLM judge failed: %s", e)
+        return {
+            "iteration": iteration,
+            "needs_more_retrieval": False,
+            "crag_finished": True,
+        }
+
+
+# ========== Node 7: tool_executor ==========
+async def tool_executor_node(state: AgentState) -> dict[str, Any]:
+    """执行 LLM 在 answer 阶段请求的工具调用."""
+    msgs = list(state.get("messages") or [])
+    last_ai = next((m for m in reversed(msgs)
+                    if hasattr(m, "type") and m.type == "ai"), None)
+    tool_calls = getattr(last_ai, "tool_calls", None) or []
+
+    if not tool_calls:
+        return {"tool_results": []}
+
+    results: list[dict[str, Any]] = []
+    for tc in tool_calls:
+        name = tc.get("name", "")
+        args = tc.get("args", {})
+        if isinstance(args, str):
+            try:
+                args = json.loads(args)
+            except json.JSONDecodeError:
+                args = {}
+        try:
+            out = await execute_tool(name, args)
+        except Exception as e:  # noqa: BLE001
+            out = f"工具执行异常: {e}"
+        results.append({"name": name, "args": args, "output": out})
+
+    return {
+        "tool_results": results,
+        "tool_calls": [{"name": r["name"], "args": r["args"]} for r in results],
+    }

app/agents/prompts.py

@@ -0,0 +1,68 @@
+"""中英系统提示词. 集中管理, 便于 A/B 调优."""
+
+# 路由判断提示
+ROUTE_PROMPT = """你是一名 query 路由器. 根据用户问题, 决定走哪条路:
+
+- "direct": 闲聊/通用知识/不需检索 (如"你好", "今天天气")
+- "retrieve": 需要知识库检索 (绝大多数问题)
+- "multi_step": 复杂多步, 需拆解为多个子问题
+
+仅输出一个 JSON, 不要解释: {"route": "direct"|"retrieve"|"multi_step", "reason": "<20字内>"}
+"""
+
+
+# 查询改写提示 (用于提高检索召回)
+QUERY_REWRITE_PROMPT = """你是查询改写助手. 给定用户的原始问题, 生成 1-3 个改写版本, 用于提升向量检索召回率.
+
+策略:
+- 加入同义词 / 别名
+- 改写为更具体的陈述句
+- 如果是缩写, 展开全称
+
+仅输出 JSON: {{"rewrites": ["...", "..."]}}
+
+原始问题: {query}
+"""
+
+
+# 答案生成主提示 (含引用)
+ANSWER_PROMPT = """你是用户的私人智能客服, 基于以下检索到的文档片段回答问题.
+
+要求:
+- 严格基于 <context> 标签内的内容回答, 不可编造
+- 引用时用 [1] [2] 这样的角标, 末尾"参考:"列出对应来源
+- 如果 <context> 不包含答案, 直接说"未在知识库中找到相关信息"
+- 用 {LOCALE} 回答 (zh=中文, en=English)
+- 简洁, 不超过 500 字, 除非问题本身要求长文
+
+<context>
+{context}
+</context>
+
+用户问题: {query}
+"""
+
+
+# CRAG 评估提示 (LLM judge, 仅在 rerank 分数 0.3-0.7 模糊区间触发)
+CRAG_EVAL_PROMPT = """你是一名 RAG 质量评估员. 给定用户问题 + 检索到的文档摘要, 判断:
+
+- "sufficient": 文档充分回答了问题
+- "insufficient": 文档不够, 需要重新检索 (用其他关键词)
+- "irrelevant": 文档与问题无关, 直接告诉用户找不到
+
+仅输出 JSON: {{"verdict": "sufficient"|"insufficient"|"irrelevant", "reason": "<30字内>"}}
+
+问题: {query}
+
+文档摘要 (top-{n}):
+{docs_summary}
+"""
+
+
+# 多步拆解
+MULTI_STEP_PROMPT = """你是任务规划员. 把用户复杂问题拆解为 2-4 个可独立检索的子问题.
+
+仅输出 JSON: {{"steps": ["子问题1", "子问题2", ...]}}
+
+用户问题: {query}
+"""

app/agents/state.py

@@ -0,0 +1,115 @@
+"""AgentState - LangGraph 跨节点状态.
+
+使用 TypedDict 而不是 Pydantic, 因为 LangGraph 内置 add_messages reducer
+需要 Annotated[Sequence[BaseMessage], add_messages] 这样的类型签名.
+"""
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, Sequence, TypedDict
+
+from langchain_core.documents import Document
+from langchain_core.messages import BaseMessage
+from langgraph.graph.message import add_messages
+
+from app.services.vector_store import RetrievalHit
+
+
+RouteDecision = Literal["direct", "retrieve", "multi_step"]
+
+
+class AgentState(TypedDict, total=False):
+    """LangGraph 跨节点状态. total=False 让所有字段可选, 各 node 自行填充."""
+
+    # ===== 基础 =====
+    messages: Annotated[Sequence[BaseMessage], add_messages]
+    session_id: str
+    user_id: str
+    locale: str  # "zh" | "en"
+
+    # ===== 路由 =====
+    route_decision: RouteDecision
+    query_rewritten: str  # 改写后的查询
+    plan: list[str]  # 多步拆解的子任务
+
+    # ===== 检索 =====
+    retrieved: list[RetrievalHit]
+    reranked: list[RetrievalHit]
+    retrieved_doc_ids: list[str]  # 命中 doc 列表 (用于 SSE retrieval 事件)
+
+    # ===== 引用 =====
+    citations: list[dict[str, Any]]  # [{doc_id, page, snippet, score, source}]
+
+    # ===== 工具 =====
+    tool_calls: list[dict[str, Any]]  # 工具调用历史
+    tool_results: list[dict[str, Any]]  # 工具结果摘要
+
+    # ===== CRAG 自校正 =====
+    iteration: int
+    max_iterations: int
+    relevance_score: float  # top-1 rerank score, 0-1
+    relevance_verdict: Literal["relevant", "ambiguous", "irrelevant"]
+    needs_more_retrieval: bool
+    crag_finished: bool
+
+    # ===== 元数据 =====
+    elapsed_ms: int
+    final_answer: str
+    error: str | None
+
+
+# ========== State helpers ==========
+def empty_state_for(session_id: str, user_id: str = "default", locale: str = "zh") -> AgentState:
+    from app.config import settings
+
+    return AgentState(
+        messages=[],
+        session_id=session_id,
+        user_id=user_id,
+        locale=locale,
+        route_decision="retrieve",
+        query_rewritten="",
+        plan=[],
+        retrieved=[],
+        reranked=[],
+        retrieved_doc_ids=[],
+        citations=[],
+        tool_calls=[],
+        tool_results=[],
+        iteration=0,
+        max_iterations=settings.crag_max_iterations,
+        relevance_score=0.0,
+        relevance_verdict="ambiguous",
+        needs_more_retrieval=False,
+        crag_finished=False,
+        elapsed_ms=0,
+        final_answer="",
+        error=None,
+    )
+
+
+def messages_to_lc(messages: list[dict[str, Any]] | list[BaseMessage]) -> list[BaseMessage]:
+    """业务侧 dict 消息列表 (来自 SQLite) 转为 LangChain BaseMessage 列表."""
+    from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+
+    out: list[BaseMessage] = []
+    for m in messages:
+        if hasattr(m, "type"):
+            out.append(m)  # 已经是 BaseMessage
+            continue
+        role = m.get("role", "user")
+        content = m.get("content", "")
+        if role == "system":
+            out.append(SystemMessage(content=content))
+        elif role == "user":
+            out.append(HumanMessage(content=content))
+        elif role == "assistant":
+            extra = {}
+            if m.get("tool_calls"):
+                extra["tool_calls"] = m["tool_calls"]
+            out.append(AIMessage(content=content, **extra))
+        elif role == "tool":
+            out.append(ToolMessage(
+                content=content,
+                tool_call_id=m.get("tool_call_id", ""),
+            ))
+    return out

app/agents/tools.py

@@ -0,0 +1,276 @@
+"""Pydantic AI 工具集 (供 LangGraph tool_executor 节点调用).
+
+工具列表:
+- summarize_document: 总结指定文档
+- compare_documents: 对比 2 个文档的某方面
+- calculate: 安全数学计算 (用 AST 而不是 eval)
+- list_documents: 列出已上传的文档
+- get_current_time: 当前时间 (调试用)
+"""
+from __future__ import annotations
+
+import ast
+import datetime as _dt
+import logging
+import operator
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from app.models import db
+from app.services.embedding import get_embedder
+from app.services.vector_store import hybrid_query
+
+logger = logging.getLogger(__name__)
+
+
+# ========== Tool schemas (OpenAI function calling 格式) ==========
+TOOL_SCHEMAS: list[dict[str, Any]] = [
+    {
+        "type": "function",
+        "function": {
+            "name": "summarize_document",
+            "description": "根据 doc_id 总结指定文档的主要内容 (取前若干 chunks 拼接 + LLM 摘要).",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "doc_id": {
+                        "type": "string",
+                        "description": "要总结的文档 ID",
+                    },
+                    "max_chunks": {
+                        "type": "integer",
+                        "description": "最多取前多少个 chunk (默认 30)",
+                        "default": 30,
+                    },
+                },
+                "required": ["doc_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "compare_documents",
+            "description": "对比两个文档在某方面的异同. 返回结构化对比结果.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "doc_id_a": {"type": "string"},
+                    "doc_id_b": {"type": "string"},
+                    "aspect": {
+                        "type": "string",
+                        "description": "对比的方面, 如 '技术选型', '营收', '风险' 等",
+                    },
+                },
+                "required": ["doc_id_a", "doc_id_b", "aspect"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "calculate",
+            "description": "安全地计算数学表达式 (加减乘除/括号/比较), 用 AST 解析避免注入.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "expression": {
+                        "type": "string",
+                        "description": "数学表达式, 如 '(2+3)*4'",
+                    },
+                },
+                "required": ["expression"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "list_documents",
+            "description": "列出已上传的所有文档 (ID + 文件名 + 状态).",
+            "parameters": {
+                "type": "object",
+                "properties": {},
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_current_time",
+            "description": "获取服务器当前时间 (UTC / 本地时区).",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "tz": {
+                        "type": "string",
+                        "description": "时区, 如 'UTC', 'Asia/Shanghai'. 默认 UTC",
+                        "default": "UTC",
+                    },
+                },
+            },
+        },
+    },
+]
+
+
+# ========== 工具实现 ==========
+async def tool_summarize_document(args: dict[str, Any]) -> str:
+    doc_id = args.get("doc_id")
+    if not doc_id:
+        return "❌ 缺少 doc_id"
+    doc = db.doc_get(doc_id)
+    if doc is None:
+        return f"❌ 文档 {doc_id} 不存在"
+
+    chunks = db.chunk_get_by_doc(doc_id, limit=int(args.get("max_chunks", 30)))
+    if not chunks:
+        return f"❌ 文档 {doc_id} 暂无内容"
+
+    text = "\n\n".join(c["text"] for c in chunks)
+    # 简单截断前 6000 字给 LLM 摘要
+    snippet = text[:6000]
+
+    from app.llm.factory import get_llm
+    llm = get_llm()
+    resp = await llm.chat(
+        messages=[
+            {"role": "system", "content": "你是文档摘要助手. 用中文输出简洁摘要, 列出主要章节和关键事实."},
+            {"role": "user", "content": f"请摘要以下内容 (来自 {doc.get('filename', doc_id)}):\n\n{snippet}"},
+        ],
+        temperature=0.3,
+        max_tokens=600,
+    )
+    return resp.content or "(空)"
+
+
+async def tool_compare_documents(args: dict[str, Any]) -> str:
+    doc_a_id = args.get("doc_id_a")
+    doc_b_id = args.get("doc_id_b")
+    aspect = args.get("aspect", "整体")
+    if not (doc_a_id and doc_b_id):
+        return "��� 缺少 doc_id_a 或 doc_id_b"
+
+    chunks_a = db.chunk_get_by_doc(doc_a_id, limit=20)
+    chunks_b = db.chunk_get_by_doc(doc_b_id, limit=20)
+    if not chunks_a or not chunks_b:
+        return f"❌ 文档 {doc_a_id if not chunks_a else doc_b_id} 无内容"
+
+    text_a = "\n".join(c["text"] for c in chunks_a)[:3000]
+    text_b = "\n".join(c["text"] for c in chunks_b)[:3000]
+
+    from app.llm.factory import get_llm
+    llm = get_llm()
+    resp = await llm.chat(
+        messages=[
+            {"role": "system", "content": "你是文档对比助手. 输出 Markdown 表格, 列出差異与相同点."},
+            {"role": "user", "content": (
+                f"对比以下两份文档的「{aspect}」方面.\n\n"
+                f"## 文档 A\n{text_a}\n\n## 文档 B\n{text_b}\n\n"
+                f"输出: 1) 关键差异 (表格) 2) 相同点 3) 建议"
+            )},
+        ],
+        temperature=0.3,
+        max_tokens=800,
+    )
+    return resp.content or "(空)"
+
+
+_BIN_OPS = {
+    ast.Add: operator.add, ast.Sub: operator.sub,
+    ast.Mult: operator.mul, ast.Div: operator.truediv,
+    ast.FloorDiv: operator.floordiv, ast.Mod: operator.mod,
+    ast.Pow: operator.pow,
+}
+_CMP_OPS = {
+    ast.Eq: operator.eq, ast.NotEq: operator.ne,
+    ast.Lt: operator.lt, ast.LtE: operator.le,
+    ast.Gt: operator.gt, ast.GtE: operator.ge,
+}
+_UNARY_OPS = {ast.UAdd: operator.pos, ast.USub: operator.neg}
+
+
+def _safe_eval(node: ast.AST) -> float | bool:
+    if isinstance(node, ast.Expression):
+        return _safe_eval(node.body)
+    if isinstance(node, ast.Constant):
+        if isinstance(node.value, (int, float)):
+            return node.value
+        raise ValueError(f"不支持的字面量: {node.value!r}")
+    if isinstance(node, ast.BinOp):
+        op = _BIN_OPS.get(type(node.op))
+        if op is None:
+            raise ValueError(f"不支持的二元运算: {type(node.op).__name__}")
+        return op(_safe_eval(node.left), _safe_eval(node.right))
+    if isinstance(node, ast.UnaryOp):
+        op = _UNARY_OPS.get(type(node.op))
+        if op is None:
+            raise ValueError(f"不支持的一元运算: {type(node.op).__name__}")
+        return op(_safe_eval(node.operand))
+    if isinstance(node, ast.Compare):
+        left = _safe_eval(node.left)
+        for cmp_op, right_node in zip(node.ops, node.comparators):
+            op = _CMP_OPS.get(type(cmp_op))
+            if op is None:
+                raise ValueError(f"不支持的比较: {type(cmp_op).__name__}")
+            left = op(left, _safe_eval(right_node))
+            if not left:
+                return False
+        return True
+    raise ValueError(f"不支持的语法: {ast.dump(node)}")
+
+
+async def tool_calculate(args: dict[str, Any]) -> str:
+    expr = args.get("expression", "")
+    if not expr:
+        return "❌ 缺少 expression"
+    try:
+        tree = ast.parse(expr, mode="eval")
+        result = _safe_eval(tree)
+        return f"{expr} = {result}"
+    except Exception as e:  # noqa: BLE001
+        return f"❌ 计算失败: {e}"
+
+
+async def tool_list_documents(args: dict[str, Any]) -> str:
+    docs = db.doc_list(limit=200)
+    if not docs:
+        return "暂无已上传文档"
+    lines = [f"- {d['id'][:8]}…  {d['filename']}  (chunks={d.get('chunk_count', 0)}, status={d.get('status', '?')})" for d in docs]
+    return "已上传文档:\n" + "\n".join(lines)
+
+
+async def tool_get_current_time(args: dict[str, Any]) -> str:
+    tz = args.get("tz", "UTC")
+    try:
+        from zoneinfo import ZoneInfo
+        now = _dt.datetime.now(ZoneInfo(tz))
+    except Exception:  # noqa: BLE001
+        now = _dt.datetime.utcnow()
+    return now.strftime("%Y-%m-%d %H:%M:%S %Z")
+
+
+# ========== 工具路由表 ==========
+TOOL_FUNCS = {
+    "summarize_document": tool_summarize_document,
+    "compare_documents": tool_compare_documents,
+    "calculate": tool_calculate,
+    "list_documents": tool_list_documents,
+    "get_current_time": tool_get_current_time,
+}
+
+
+async def execute_tool(name: str, args: dict[str, Any]) -> str:
+    """统一工具执行入口."""
+    fn = TOOL_FUNCS.get(name)
+    if fn is None:
+        return f"❌ 未知工具: {name}"
+    try:
+        return await fn(args)
+    except Exception as e:  # noqa: BLE001
+        logger.exception("Tool %s failed", name)
+        return f"❌ 工具执行失败: {e}"
+
+
+__all__ = ["TOOL_SCHEMAS", "TOOL_FUNCS", "execute_tool"]

app/api/chat.py

@@ -0,0 +1,241 @@
+"""阶段 3 chat 端点: 接 LangGraph agent, 完整 AG-UI 9 类事件.
+
+事件流顺序 (典型):
+  thinking        {content: "用户在询问财务数据..."}
+  agent_step      {node: "route", status: "running"}
+  agent_step      {node: "route", status: "done"}
+  retrieval       {doc_ids: [...], scores: [...]}
+  citation        {doc_id, page, snippet, score}
+  token           {content: "..."}      (多次, 流式)
+  agent_step      {node: "evaluate", status: "done"}
+  done            {usage, total_ms}
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+import uuid
+from collections.abc import AsyncIterator
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+from langchain_core.messages import HumanMessage
+
+from app.agents.graph import get_compiled_graph
+from app.agents.nodes import answer_node_stream
+from app.agents.state import empty_state_for
+from app.config import settings
+from app.llm.base import LLMMessage
+from app.llm.factory import get_llm
+from app.models import db
+from app.models.schemas import ChatRequest, ChatResponse
+from app.streaming.events import (
+    sse_done,
+    sse_error,
+    sse_format,
+    EV_AGENT_STEP,
+    EV_CITATION,
+    EV_DONE,
+    EV_ERROR,
+    EV_PROGRESS,
+    EV_RETRIEVAL,
+    EV_THINKING,
+    EV_TOKEN,
+    EV_TOOL_CALL,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/chat", tags=["chat"])
+
+
+# ========== 兜底: 阶段 1 简单直答 (route=direct / 无 agent) ==========
+_FALLBACK_SYSTEM = (
+    "你是一个有帮助的中文 AI 助手。"
+    "回答应简洁、准确、礼貌。如不知道答案请直接说明。"
+)
+
+
+@router.post("", response_model=ChatResponse)
+async def chat_simple(req: ChatRequest) -> ChatResponse:
+    """非流式 chat: 跑完整 agent 但收集完整结果再返."""
+    started = time.time()
+    try:
+        final_state, events_log = await _run_agent(req)
+    except Exception as e:  # noqa: BLE001
+        logger.exception("chat failed")
+        raise HTTPException(status_code=502, detail=str(e)) from e
+
+    answer = final_state.get("final_answer") or "(无回答)"
+    return ChatResponse(
+        session_id=req.session_id,
+        message_id=uuid.uuid4().hex,
+        content=answer,
+        citations=final_state.get("citations", []),
+        agent_steps=events_log,
+        usage={},  # 阶段 3 暂不聚合
+        total_ms=int((time.time() - started) * 1000),
+    )
+
+
+@router.post("/stream")
+async def chat_stream(req: ChatRequest) -> StreamingResponse:
+    """SSE 流式 chat: 完整 AG-UI 事件."""
+    return StreamingResponse(
+        _agent_event_stream(req),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache, no-transform",
+            "X-Accel-Buffering": "no",  # 关闭 nginx 缓冲
+        },
+    )
+
+
+# ========== 核心: 跑 agent + 产生 SSE 事件 ==========
+async def _agent_event_stream(req: ChatRequest) -> AsyncIterator[str]:
+    """驱动 agent + 把过程映射为 AG-UI 事件."""
+    queue: asyncio.Queue[tuple[str, dict] | None] = asyncio.Queue(maxsize=256)
+
+    async def emit(event: str, data: dict) -> None:
+        await queue.put((event, data))
+
+    async def runner() -> None:
+        try:
+            await _run_agent(req, emit=emit)
+        except Exception as e:  # noqa: BLE001
+            logger.exception("agent runner failed")
+            await emit(EV_ERROR, {"code": "agent_failed", "message": str(e), "retryable": True})
+        finally:
+            await queue.put(None)
+
+    task = asyncio.create_task(runner())
+
+    # 启动心跳
+    started = time.time()
+    try:
+        while True:
+            try:
+                item = await asyncio.wait_for(queue.get(), timeout=15.0)
+            except asyncio.TimeoutError:
+                # 心跳
+                yield ": keepalive\n\n"
+                continue
+            if item is None:
+                break
+            event, data = item
+            yield sse_format(event, data)
+    finally:
+        if not task.done():
+            task.cancel()
+
+    # done
+    yield sse_done(total_ms=int((time.time() - started) * 1000))
+
+
+async def _run_agent(
+    req: ChatRequest,
+    emit=None,  # async callable | None
+) -> tuple[dict, list[dict]]:
+    """执行 agent. emit 可选, 用于 SSE 推送中间事件.
+
+    Returns:
+        (final_state_dict, events_log)
+    """
+    started = time.time()
+    events_log: list[dict] = []
+
+    async def _emit(event: str, data: dict) -> None:
+        if emit is not None:
+            await emit(event, data)
+        events_log.append({"event": event, "data": data, "ts": time.time()})
+
+    # 1. 加载历史消息
+    history_rows = db.message_list_by_session(req.session_id, limit=20)
+    from app.agents.state import messages_to_lc
+    history_msgs = messages_to_lc([
+        {"role": r["role"], "content": r["content"]}
+        for r in history_rows
+    ])
+
+    # 2. 添加本轮 user message
+    new_user_msg = HumanMessage(content=req.message)
+    history_msgs.append(new_user_msg)
+
+    # 3. 初始化 state
+    state = empty_state_for(req.session_id, locale=req.locale)
+    state["messages"] = history_msgs
+
+    # 4. 记录 user message 到 SQLite
+    db.session_upsert(req.session_id)
+    db.message_insert({
+        "id": uuid.uuid4().hex,
+        "session_id": req.session_id,
+        "role": "user",
+        "content": req.message,
+    })
+
+    # 5. 跑 LangGraph (retrieval loop)
+    try:
+        graph = await get_compiled_graph()
+    except Exception as e:  # noqa: BLE001
+        await _emit(EV_ERROR, {"code": "graph_init_failed", "message": str(e)})
+        raise
+
+    config = {"configurable": {"thread_id": req.session_id}}
+    final_state: dict = dict(state)
+
+    # 直接用 graph.ainvoke, 拿最终 state
+    try:
+        result = await graph.ainvoke(state, config=config)
+        final_state.update(result)
+    except Exception as e:  # noqa: BLE001
+        logger.exception("graph.ainvoke failed")
+        await _emit(EV_ERROR, {"code": "graph_failed", "message": str(e)})
+        raise
+
+    # 6. 推送检索事件
+    if final_state.get("retrieved_doc_ids"):
+        await _emit(EV_RETRIEVAL, {
+            "doc_ids": final_state["retrieved_doc_ids"],
+            "count": len(final_state.get("retrieved", [])),
+            "scores": [round(h.score, 4) for h in final_state.get("retrieved", [])[:10]],
+        })
+    if final_state.get("citations"):
+        await _emit(EV_PROGRESS, {"pct": 60, "label": "已生成引用, 正在回答..."})
+
+    # 7. 跑 answer 流式 (直接调 LLM, 不走 graph)
+    await _emit(EV_AGENT_STEP, {"node": "answer", "status": "running"})
+
+    async def _on_token(content: str) -> None:
+        await _emit(EV_TOKEN, {"content": content})
+
+    async def _on_citation(c: dict) -> None:
+        await _emit(EV_CITATION, c)
+
+    async def _on_thinking(content: str) -> None:
+        await _emit(EV_THINKING, {"content": content})
+
+    answer_update = await answer_node_stream(
+        final_state,
+        on_token=_on_token,
+        on_citation=_on_citation,
+        on_thinking=_on_thinking,
+    )
+    final_state.update(answer_update)
+
+    await _emit(EV_AGENT_STEP, {"node": "answer", "status": "done"})
+    await _emit(EV_PROGRESS, {"pct": 100, "label": "完成"})
+
+    # 8. 记录 assistant message 到 SQLite
+    elapsed = int((time.time() - started) * 1000)
+    db.message_insert({
+        "id": uuid.uuid4().hex,
+        "session_id": req.session_id,
+        "role": "assistant",
+        "content": final_state.get("final_answer", ""),
+        "citations": final_state.get("citations", []),
+    })
+
+    return final_state, events_log

app/api/documents.py

@@ -0,0 +1,100 @@
+"""文档管理 API. 阶段 2: 完整 upload / list / delete / get / chunks."""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, File, HTTPException, Query, UploadFile
+
+from app.core.errors import DocumentNotFoundError
+from app.models import db
+from app.models.schemas import DocumentChunk, IngestResult
+from app.services.ingestion import (
+    delete_document,
+    get_document,
+    ingest_bytes,
+    list_documents,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/documents", tags=["documents"])
+
+
+@router.get("")
+async def list_docs(
+    limit: int = Query(default=100, ge=1, le=500),
+    offset: int = Query(default=0, ge=0),
+) -> dict:
+    docs = list_documents(limit=limit)
+    return {
+        "documents": docs[offset : offset + limit],
+        "total": len(docs),
+    }
+
+
+@router.get("/{doc_id}")
+async def get_doc(doc_id: str) -> dict:
+    doc = get_document(doc_id)
+    if doc is None:
+        raise DocumentNotFoundError(f"Document {doc_id} not found", code="doc_not_found")
+    return doc
+
+
+@router.get("/{doc_id}/chunks")
+async def list_chunks(
+    doc_id: str,
+    limit: int = Query(default=200, ge=1, le=1000),
+    offset: int = Query(default=0, ge=0),
+) -> dict:
+    """获取文档的 chunks 列表, 用于前端预览拆分结果.
+
+    返回顺序: 按 chunk_index ASC. 包含 text / token_count / page_no / heading / context_prefix.
+    """
+    doc = get_document(doc_id)
+    if doc is None:
+        raise DocumentNotFoundError(f"Document {doc_id} not found", code="doc_not_found")
+    rows = db.chunk_get_by_doc(doc_id, limit=limit + offset)
+    # 截取 offset
+    rows = rows[offset : offset + limit]
+    return {
+        "doc_id": doc_id,
+        "chunks": [DocumentChunk(**r).model_dump() for r in rows],
+        "total": doc.get("chunk_count", len(rows)),
+        "returned": len(rows),
+    }
+
+
+@router.post("/upload", response_model=IngestResult)
+async def upload(file: UploadFile = File(...)) -> IngestResult:
+    """上传并摄入文档. 支持 PDF / DOCX / 图片.
+
+    流程: 读字节 -> 摄入编排器 (内部 SHA256 查重 + 解析 + 分块 + 向量化 + 入库)
+    """
+    if file.filename is None:
+        raise HTTPException(status_code=400, detail="filename missing")
+
+    # 限制大小 (50MB; HF Space free 16GB RAM 下够用)
+    MAX_BYTES = 50 * 1024 * 1024
+    content = await file.read(MAX_BYTES + 1)
+    if len(content) > MAX_BYTES:
+        raise HTTPException(
+            status_code=413,
+            detail=f"File too large (> {MAX_BYTES // 1024 // 1024}MB). "
+                   "Consider chunked upload via S3/R2 (TODO 阶段 5).",
+        )
+
+    try:
+        result = await ingest_bytes(content=content, filename=file.filename)
+    except Exception as e:  # noqa: BLE001
+        # 已记录到 SQLite; 返回 502
+        logger.exception("Upload failed")
+        raise HTTPException(status_code=502, detail=f"Ingest failed: {e}") from e
+
+    return result
+
+
+@router.delete("/{doc_id}")
+async def delete_doc(doc_id: str) -> dict:
+    ok = await delete_document(doc_id)
+    if not ok:
+        raise DocumentNotFoundError(f"Document {doc_id} not found", code="doc_not_found")
+    return {"doc_id": doc_id, "deleted": True}

app/api/health.py

@@ -0,0 +1,55 @@
+"""健康检查 + 探活."""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Request
+
+from app.config import settings
+from app.deps import get_llm, persist_status
+from app.models.schemas import HealthStatus
+
+router = APIRouter(tags=["health"])
+logger = logging.getLogger(__name__)
+
+
+@router.get("/healthz", response_model=HealthStatus)
+async def healthz() -> HealthStatus:
+    """Liveness 探针. 不检查外部依赖, 永远返回 ok (只要进程在)."""
+    return HealthStatus(
+        status="ok",
+        llm=True,  # 进程在即代表 LLM 单例已建 (或尝试过)
+        persist=persist_status(),
+        chroma=False,  # 阶段 2 接入
+        version=settings.app_version,
+    )
+
+
+@router.get("/readyz", response_model=HealthStatus)
+async def readyz(request: Request) -> HealthStatus:
+    """Readiness 探针. 检查 LLM 实际可达 + Chroma + 持久化模式."""
+    llm_ok = False
+    try:
+        llm = get_llm()
+        llm_ok = await llm.health_check()
+    except Exception as e:  # noqa: BLE001
+        logger.warning("readyz: LLM health check error: %s", e)
+
+    chroma_ok = False
+    try:
+        from app.services.vector_store import get_chroma
+        _, coll, _ = get_chroma()
+        chroma_ok = coll.count() >= 0  # 任意 count 都不报错即说明连接通
+    except Exception as e:  # noqa: BLE001
+        logger.warning("readyz: Chroma check error: %s", e)
+
+    persist = persist_status()
+    overall = "ok" if (llm_ok and chroma_ok) else "degraded"
+
+    return HealthStatus(
+        status=overall,
+        llm=llm_ok,
+        persist=persist,
+        chroma=chroma_ok,
+        version=settings.app_version,
+    )

app/api/sessions.py

@@ -0,0 +1,59 @@
+"""会话管理 API (阶段 3 接入 LangGraph checkpoint + SQLite)."""
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+
+from fastapi import APIRouter, HTTPException
+from langchain_core.messages import HumanMessage, AIMessage
+
+from app.agents.graph import get_compiled_graph
+from app.agents.state import messages_to_lc
+from app.models import db
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/sessions", tags=["sessions"])
+
+
+@router.get("")
+async def list_sessions(limit: int = 50) -> dict:
+    sessions = db.session_list(limit=limit)
+    return {"sessions": sessions, "total": len(sessions)}
+
+
+@router.get("/{session_id}")
+async def get_session(session_id: str) -> dict:
+    """返回会话 + 消息历史."""
+    session = db.session_get(session_id)
+    if session is None:
+        # 可能还没消息, 但 LangGraph checkpoint 里有. 试一下
+        pass
+    messages = db.message_list_by_session(session_id)
+    return {
+        "session": session or {"id": session_id, "title": None, "message_count": 0},
+        "messages": messages,
+    }
+
+
+@router.delete("/{session_id}")
+async def delete_session(session_id: str) -> dict:
+    """删除会话. SQLite + LangGraph checkpoint 一并清."""
+    db.session_delete(session_id)
+    # LangGraph checkpoint 删: 用其内部 API
+    try:
+        graph = await get_compiled_graph()
+        checkpointer = graph.checkpointer  # AsyncSqliteSaver
+        if hasattr(checkpointer, "adelete_thread"):
+            await checkpointer.adelete_thread(session_id)
+    except Exception as e:  # noqa: BLE001
+        logger.warning("LangGraph checkpoint delete failed for %s: %s", session_id, e)
+    return {"session_id": session_id, "deleted": True}
+
+
+@router.post("")
+async def create_session(title: str | None = None) -> dict:
+    """新建会话. 返回 session_id, 供后续 chat 使用."""
+    session_id = uuid.uuid4().hex
+    db.session_upsert(session_id, title=title)
+    return {"session_id": session_id, "title": title}

app/config.py

@@ -0,0 +1,187 @@
+"""全量环境变量配置 (Pydantic Settings).
+
+修改默认值时, 注意区分:
+- "工程常量" (代码内调用方期望) → 直接写死
+- "环境变量" (部署时可调) → 字段, 通过 env 覆盖
+"""
+from __future__ import annotations
+
+# Monkey patch transformers to bypass torch.load safety check on old PyTorch versions (macOS x86_64)
+try:
+    import transformers.utils.import_utils
+    transformers.utils.import_utils.check_torch_load_is_safe = lambda *args, **kwargs: None
+except ImportError:
+    pass
+
+try:
+    import transformers.modeling_utils
+    transformers.modeling_utils.check_torch_load_is_safe = lambda *args, **kwargs: None
+except ImportError:
+    pass
+
+# Force CPU device for PyTorch MPS on Intel Macs to prevent NotImplementedError
+try:
+    import torch
+    torch.backends.mps.is_available = lambda: False
+    torch.backends.mps.is_built = lambda: False
+    if hasattr(torch, "mps"):
+        torch.mps.is_available = lambda: False
+except ImportError:
+    pass
+
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+    # ========== App ==========
+    app_name: str = "ai-chatbot"
+    app_version: str = "0.1.0"
+    app_host: str = "0.0.0.0"
+    app_port: int = 7860
+    log_level: str = "INFO"
+
+    # ========== LLM Provider ==========
+    llm_provider: Literal["minimax", "openai", "anthropic", "qwen"] = "minimax"
+
+    # MiniMax-M3 (OpenAI 兼容)
+    minimax_api_key: SecretStr = Field(default=SecretStr(""))
+    minimax_base_url: str = "https://api.MiniMax.com/v1"
+    minimax_model: str = "MiniMax-M3"
+
+    # 其他 provider 备用 (切换 llm_provider 时生效)
+    openai_api_key: SecretStr = Field(default=SecretStr(""))
+    anthropic_api_key: SecretStr = Field(default=SecretStr(""))
+    qwen_api_key: SecretStr = Field(default=SecretStr(""))
+
+    # CRAG evaluate 阶段 2 用的 LLM judge (可选更小/更便宜)
+    llm_judge_model: str = "MiniMax-M3"
+
+    # ========== Embedding & Reranker ==========
+    embedding_model: str = "BAAI/bge-m3"
+    reranker_model: str = "BAAI/bge-reranker-v2-m3"
+    embedding_device: Literal["cpu", "cuda", "mps"] = "cpu"
+    use_fp16: bool = True
+
+    # ========== 向量库 / ChromaDB ==========
+    chroma_persist_dir: str = "./data/chroma"
+    chroma_collection: str = "docs"
+    enable_colbert: bool = True  # 三路融合开关; false 则仅 dense+sparse
+
+    # ========== 持久化 (HF Dataset repo) ==========
+    hf_persist_repo: str = ""  # 形如 "username/ai-chatbot-data". 留空禁用持久化
+    hf_token: SecretStr = Field(default=SecretStr(""))
+    persist_on_write: bool = True
+
+    # ========== 数据目录 ==========
+    data_dir: Path = Path("./data")
+    upload_dir: Path = Path("./data/uploads")
+
+    # ========== RAG / Agent ==========
+    chunk_size: int = 512
+    chunk_overlap: int = 64
+    semantic_chunking: bool = True
+    contextual_retrieval: bool = True
+    retrieval_k: int = 20
+    rerank_top_n: int = 5
+    crag_max_iterations: int = 2
+    crag_relevance_threshold: float = 0.7
+
+    # ========== LLM 缓存 ==========
+    llm_cache_enabled: bool = True
+    llm_cache_size: int = 200
+
+    # ========== 解析器 ==========
+    parser_primary: Literal["docling", "marker", "mineru", "vlm"] = "docling"
+    parser_fallback: Literal["docling", "marker", "mineru", "vlm"] = "marker"
+    parser_enable_ocr: bool = True
+    parser_table_structure: bool = True
+
+    # ========== 可观测性 ==========
+    langsmith_tracing: bool = False
+    langchain_api_key: SecretStr = Field(default=SecretStr(""))
+    langchain_project: str = "ai-chatbot"
+
+    # ========== CORS ==========
+    allowed_origins: list[str] = Field(
+        default_factory=lambda: [
+            "http://localhost:5173",
+            "http://localhost:3000",
+        ]
+    )
+
+    @field_validator("allowed_origins", mode="before")
+    @classmethod
+    def _parse_origins(cls, v: Any) -> list[str]:
+        """支持 JSON 数组字符串 或 python list."""
+        if isinstance(v, str):
+            v = v.strip()
+            if v.startswith("["):
+                return json.loads(v)
+            return [o.strip() for o in v.split(",") if o.strip()]
+        if isinstance(v, list):
+            return v
+        raise ValueError("allowed_origins must be a list or JSON string")
+
+    @field_validator("data_dir", "upload_dir", mode="after")
+    @classmethod
+    def _abs_path(cls, v: Path) -> Path:
+        return Path(v).expanduser().resolve()
+
+    # ========== 派生 ==========
+    @property
+    def sqlite_dir(self) -> Path:
+        p = self.data_dir / "sqlite"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def chroma_dir(self) -> Path:
+        p = Path(self.chroma_persist_dir).expanduser().resolve()
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def hf_cache_dir(self) -> Path:
+        p = self.data_dir / ".cache" / "huggingface"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @property
+    def sqlite_db_path(self) -> Path:
+        return self.sqlite_dir / "app.db"
+
+    @property
+    def langgraph_db_path(self) -> Path:
+        return self.sqlite_dir / "langgraph.db"
+
+    @property
+    def upload_path(self) -> Path:
+        p = self.upload_dir
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    def is_persist_enabled(self) -> bool:
+        return bool(self.hf_persist_repo and self.hf_token.get_secret_value())
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """单例 settings (避免重复读取环境变量)."""
+    return Settings()
+
+
+# 全局访问点
+settings = get_settings()

app/core/errors.py

@@ -0,0 +1,71 @@
+"""自定义异常 + FastAPI 异常处理."""
+from __future__ import annotations
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+
+class AppError(Exception):
+    """应用层业务异常的基类."""
+
+    code: str = "app_error"
+    status_code: int = 500
+    retryable: bool = False
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status_code: int | None = None,
+        retryable: bool | None = None,
+        detail: dict | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        if code is not None:
+            self.code = code
+        if status_code is not None:
+            self.status_code = status_code
+        if retryable is not None:
+            self.retryable = retryable
+        self.detail = detail or {}
+
+
+class DocumentNotFoundError(AppError):
+    code = "document_not_found"
+    status_code = 404
+
+
+class IngestionFailedError(AppError):
+    code = "ingestion_failed"
+    status_code = 500
+    retryable = True
+
+
+class LLMUnavailableError(AppError):
+    code = "llm_unavailable"
+    status_code = 503
+    retryable = True
+
+
+class VectorStoreUnavailableError(AppError):
+    code = "vector_store_unavailable"
+    status_code = 503
+    retryable = True
+
+
+def install_exception_handlers(app: FastAPI) -> None:
+    """挂载全局异常处理. 由 main.py 在创建 app 后调用."""
+
+    @app.exception_handler(AppError)
+    async def _app_error_handler(_: Request, exc: AppError) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "code": exc.code,
+                "message": exc.message,
+                "retryable": exc.retryable,
+                "detail": exc.detail,
+            },
+        )

app/core/logging.py

@@ -0,0 +1,70 @@
+"""结构化日志 (JSON 格式, 便于 LangSmith 解析)."""
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any
+
+from app.config import settings
+
+
+class JSONFormatter(logging.Formatter):
+    """极简 JSON formatter — 生产用. 开发可切回默认."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        import json
+
+        payload: dict[str, Any] = {
+            "ts": self.formatTime(record, self.datefmt),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+        }
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        # 透传 extra 字段
+        for k, v in record.__dict__.items():
+            if k in (
+                "name", "msg", "args", "levelname", "levelno", "pathname",
+                "filename", "module", "exc_info", "exc_text", "stack_info",
+                "lineno", "funcName", "created", "msecs", "relativeCreated",
+                "thread", "threadName", "processName", "process", "message",
+                "taskName",
+            ):
+                continue
+            try:
+                json.dumps(v)
+                payload[k] = v
+            except (TypeError, ValueError):
+                payload[k] = str(v)
+        return json.dumps(payload, ensure_ascii=False)
+
+
+def setup_logging() -> None:
+    """初始化根 logger. 在 lifespan 启动时调用."""
+    root = logging.getLogger()
+    root.setLevel(settings.log_level.upper())
+
+    # 避免重复 handler
+    if root.handlers:
+        return
+
+    handler = logging.StreamHandler(sys.stdout)
+    if settings.log_level.upper() == "DEBUG":
+        handler.setFormatter(
+            logging.Formatter(
+                "%(asctime)s | %(levelname)-7s | %(name)s | %(message)s",
+                datefmt="%H:%M:%S",
+            )
+        )
+    else:
+        handler.setFormatter(JSONFormatter())
+    root.addHandler(handler)
+
+    # 降噪第三方库
+    for noisy in ("httpx", "httpcore", "openai", "chromadb", "huggingface_hub"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+
+def get_logger(name: str) -> logging.Logger:
+    return logging.getLogger(name)

app/core/paths.py

@@ -0,0 +1,45 @@
+"""Persistent disk path helpers.
+
+HF Spaces 免费版 `/data` 是持久卷挂载点 (即使容器重启也保留).
+在本地 dev 时, 退回到仓库内 `./data/`.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from app.config import settings
+
+
+def data_dir() -> Path:
+    """根数据目录 (确保存在)."""
+    p = Path(settings.data_dir).expanduser().resolve()
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def upload_dir() -> Path:
+    """用户上传的原始文件目录."""
+    p = data_dir() / "uploads"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def sqlite_dir() -> Path:
+    """SQLite 文件 (元数据 + LangGraph checkpoint) 目录."""
+    p = data_dir() / "sqlite"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def chroma_dir() -> Path:
+    """ChromaDB 持久化目录."""
+    p = data_dir() / "chroma"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def hf_cache_dir() -> Path:
+    """HuggingFace 模型缓存目录 (避免重复下载)."""
+    p = data_dir() / ".cache" / "huggingface"
+    p.mkdir(parents=True, exist_ok=True)
+    return p

app/deps.py

@@ -0,0 +1,32 @@
+"""应用级单例 (LLM, embedder, vector store, etc.) 的获取与生命周期.
+
+被 main.py lifespan 和各 router 复用. 保持依赖注入简单, 不引入 DI 框架.
+"""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from app.config import settings
+from app.llm.base import AbstractLLM
+
+if TYPE_CHECKING:
+    from app.services.persist import persist_status
+
+logger = logging.getLogger(__name__)
+
+
+def get_llm() -> AbstractLLM:
+    """从工厂取 LLM 单例. 失败时抛出 LLMUnavailableError."""
+    from app.llm.factory import get_llm as _factory_get_llm
+    return _factory_get_llm()
+
+
+async def close_llm() -> None:
+    from app.llm.factory import close_llm as _factory_close
+    await _factory_close()
+
+
+def persist_status() -> dict:
+    from app.services.persist import persist_status as _ps
+    return _ps()

app/llm/__init__.py

@@ -0,0 +1,5 @@
+"""LLM provider 抽象. 由 factory.py 根据 settings.llm_provider 选择."""
+from app.llm.base import AbstractLLM, LLMChunk, LLMMessage
+from app.llm.factory import get_llm
+
+__all__ = ["AbstractLLM", "LLMChunk", "LLMMessage", "get_llm"]

app/llm/base.py

@@ -0,0 +1,97 @@
+"""LLM provider 抽象基类 + 数据类型.
+
+设计原则:
+- 与 LangChain / Pydantic AI 解耦, 业务代码只依赖本模块
+- 流式 + 非流式接口都提供
+- 支持 tool calling (OpenAI 兼容格式)
+- 内置指数退避重试
+"""
+from __future__ import annotations
+
+import abc
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class LLMMessage:
+    """与 OpenAI ChatMessage 兼容的轻量消息结构."""
+
+    role: str  # "system" | "user" | "assistant" | "tool"
+    content: str
+    name: str | None = None
+    tool_call_id: str | None = None
+    tool_calls: list[dict[str, Any]] | None = None  # assistant 消息的 tool_calls
+
+
+@dataclass
+class ToolSpec:
+    """OpenAI 兼容的 function-calling 工具规格."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]  # JSON Schema
+
+
+@dataclass
+class LLMChunk:
+    """流式响应的单个 chunk."""
+
+    content: str = ""
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    finish_reason: str | None = None
+    usage: dict[str, int] | None = None  # 仅最后一个 chunk 携带
+
+
+@dataclass
+class LLMResponse:
+    """非流式响应的完整结果."""
+
+    content: str
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    finish_reason: str = "stop"
+    usage: dict[str, int] = field(default_factory=dict)
+    raw: Any = None  # provider 原始响应 (调试用)
+
+
+class AbstractLLM(abc.ABC):
+    """LLM provider 抽象基类."""
+
+    name: str = "abstract"
+
+    @abc.abstractmethod
+    async def chat(
+        self,
+        messages: list[LLMMessage],
+        *,
+        tools: list[ToolSpec] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        """非流式聊天."""
+
+    @abc.abstractmethod
+    def stream_chat(
+        self,
+        messages: list[LLMMessage],
+        *,
+        tools: list[ToolSpec] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[LLMChunk]:
+        """流式聊天. 必须返回 AsyncIterator (async generator)."""
+        # 抽象方法必须 yield 一次占位, 否则子类可能写错
+        # 但子类实现是 async def + yield, 所以这里只是签名
+        raise NotImplementedError
+        yield  # type: ignore[unreachable]  # pragma: no cover
+
+    @abc.abstractmethod
+    async def health_check(self) -> bool:
+        """探活: 极简调用 (如 1 token completion)."""
+
+    @abc.abstractmethod
+    async def aclose(self) -> None:
+        """关闭底层 client (httpx / AsyncOpenAI 等)."""

app/llm/factory.py

@@ -0,0 +1,104 @@
+"""LLM 工厂: 根据 settings.llm_provider 选择 provider.
+
+新增 provider 的步骤:
+1. 在 base.py 实现一个新类 (或复用 OpenAICompatibleLLM)
+2. 在本文件 _PROVIDERS 加一行
+3. 在 .env.example 暴露新 env
+"""
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+
+from app.config import settings
+from app.core.errors import LLMUnavailableError
+from app.llm.base import AbstractLLM
+from app.llm.minimax import OpenAICompatibleLLM
+
+logger = logging.getLogger(__name__)
+
+
+def _build_minimax() -> OpenAICompatibleLLM:
+    key = settings.minimax_api_key.get_secret_value()
+    if not key:
+        raise LLMUnavailableError(
+            "MINIMAX_API_KEY is empty. Set it in .env or HF Space secrets.",
+            code="llm_api_key_missing",
+        )
+    return OpenAICompatibleLLM(
+        api_key=key,
+        base_url=settings.minimax_base_url,
+        model=settings.minimax_model,
+        provider_name="minimax",
+    )
+
+
+def _build_openai() -> OpenAICompatibleLLM:
+    key = settings.openai_api_key.get_secret_value()
+    if not key:
+        raise LLMUnavailableError(
+            "OPENAI_API_KEY is empty.",
+            code="llm_api_key_missing",
+        )
+    return OpenAICompatibleLLM(
+        api_key=key,
+        base_url="https://api.openai.com/v1",
+        # 允许用 env 覆盖 model (openai_model), 没设则用 gpt-4o-mini
+        model=getattr(settings, "openai_model", "gpt-4o-mini"),
+        provider_name="openai",
+    )
+
+
+def _build_qwen() -> OpenAICompatibleLLM:
+    key = settings.qwen_api_key.get_secret_value()
+    if not key:
+        raise LLMUnavailableError(
+            "QWEN_API_KEY is empty.",
+            code="llm_api_key_missing",
+        )
+    return OpenAICompatibleLLM(
+        api_key=key,
+        # 阿里百炼 OpenAI 兼容端点
+        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+        model=getattr(settings, "qwen_model", "qwen-max"),
+        provider_name="qwen",
+    )
+
+
+def _build_anthropic() -> AbstractLLM:
+    """占位: Anthropic SDK 原生协议, 暂未实现, 留 hook."""
+    raise NotImplementedError(
+        "Anthropic provider not yet implemented. "
+        "Use openai-compatible via OpenRouter or implement anthropic.AsyncAnthropic wrapper."
+    )
+
+
+_PROVIDERS = {
+    "minimax": _build_minimax,
+    "openai": _build_openai,
+    "qwen": _build_qwen,
+    "anthropic": _build_anthropic,
+}
+
+
+@lru_cache(maxsize=1)
+def get_llm() -> AbstractLLM:
+    """单例 LLM. 在 lifespan 中调用 + 缓存."""
+    builder = _PROVIDERS.get(settings.llm_provider)
+    if builder is None:
+        raise LLMUnavailableError(
+            f"Unknown llm_provider: {settings.llm_provider}",
+            code="llm_provider_unknown",
+        )
+    logger.info("Initializing LLM provider: %s", settings.llm_provider)
+    return builder()
+
+
+async def close_llm() -> None:
+    """关闭 LLM 客户端. lifespan shutdown 时调用."""
+    try:
+        llm = get_llm()
+    except Exception:  # noqa: BLE001
+        return
+    await llm.aclose()
+    get_llm.cache_clear()

app/llm/minimax.py

@@ -0,0 +1,239 @@
+"""MiniMax-M3 provider (OpenAI 兼容协议).
+
+通过 AsyncOpenAI(base_url=...) 调用 MiniMax 端点.
+所有 OpenAI 兼容的 provider (Qwen / DeepSeek / 自部署 vLLM 等) 都可以复用本类,
+只需换 base_url 和 model.
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+
+from openai import APIError, APITimeoutError, AsyncOpenAI, RateLimitError
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from app.config import settings
+from app.core.errors import LLMUnavailableError
+from app.llm.base import (
+    AbstractLLM,
+    LLMChunk,
+    LLMMessage,
+    LLMResponse,
+    ToolSpec,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _to_openai_messages(messages: list[LLMMessage]) -> list[dict[str, Any]]:
+    """转换为本类消息 -> OpenAI ChatMessage dict."""
+    out: list[dict[str, Any]] = []
+    for m in messages:
+        d: dict[str, Any] = {"role": m.role, "content": m.content}
+        if m.name:
+            d["name"] = m.name
+        if m.tool_call_id:
+            d["tool_call_id"] = m.tool_call_id
+        if m.tool_calls:
+            d["tool_calls"] = m.tool_calls
+        out.append(d)
+    return out
+
+
+def _to_openai_tools(tools: list[ToolSpec]) -> list[dict[str, Any]]:
+    """ToolSpec -> OpenAI tools format."""
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": t.name,
+                "description": t.description,
+                "parameters": t.parameters,
+            },
+        }
+        for t in tools
+    ]
+
+
+class OpenAICompatibleLLM(AbstractLLM):
+    """OpenAI 兼容协议的通用 LLM (MiniMax / Qwen / DeepSeek / 自部署 vLLM).
+
+    之所以不叫 MiniMaxLLM: 因为实现是通用的, 通过 (base_url, model) 切换 provider.
+    factory.py 用 settings 决定具体配置.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        model: str,
+        provider_name: str = "openai-compat",
+        timeout: float = 60.0,
+    ) -> None:
+        self.name = provider_name
+        self.model = model
+        # 关键: trust_env=False 强制不走系统代理 (urllib.getproxies() / macOS System Preferences)
+        # 否则 httpx 会尝试走 127.0.0.1:7897, 若该端口代理服务不可用, TLS 握手会挂在
+        # start_tls 阶段报 "Connection error"
+        import httpx as _httpx
+        _http_client = _httpx.AsyncClient(
+            trust_env=False,
+            timeout=timeout,
+        )
+        self.client = AsyncOpenAI(
+            api_key=api_key or "EMPTY",
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=0,  # tenacity 自管
+            http_client=_http_client,
+        )
+        logger.info(
+            "LLM client init: provider=%s base_url=%s model=%s (trust_env=False, no proxy)",
+            provider_name, base_url, model,
+        )
+
+    async def aclose(self) -> None:
+        await self.client.close()
+
+    @retry(
+        retry=retry_if_exception_type((APITimeoutError, RateLimitError, APIError)),
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=1, max=10),
+        reraise=True,
+    )
+    async def chat(
+        self,
+        messages: list[LLMMessage],
+        *,
+        tools: list[ToolSpec] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> LLMResponse:
+        params: dict[str, Any] = {
+            "model": self.model,
+            "messages": _to_openai_messages(messages),
+            "temperature": temperature,
+        }
+        if max_tokens is not None:
+            params["max_tokens"] = max_tokens
+        if tools:
+            params["tools"] = _to_openai_tools(tools)
+        params.update(kwargs)
+
+        try:
+            resp = await self.client.chat.completions.create(**params)
+        except (APITimeoutError, RateLimitError, APIError) as e:
+            logger.warning("LLM chat retry: %s", e)
+            raise
+        except Exception as e:
+            raise LLMUnavailableError(
+                f"LLM call failed: {e}", retryable=False
+            ) from e
+
+        choice = resp.choices[0]
+        msg = choice.message
+        usage = (
+            {
+                "prompt_tokens": resp.usage.prompt_tokens,
+                "completion_tokens": resp.usage.completion_tokens,
+                "total_tokens": resp.usage.total_tokens,
+            }
+            if resp.usage
+            else {}
+        )
+        return LLMResponse(
+            content=msg.content or "",
+            tool_calls=[tc.model_dump() for tc in (msg.tool_calls or [])],
+            finish_reason=choice.finish_reason or "stop",
+            usage=usage,
+            raw=resp,
+        )
+
+    @retry(
+        retry=retry_if_exception_type((APITimeoutError, RateLimitError, APIError)),
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=1, max=10),
+        reraise=True,
+    )
+    async def stream_chat(
+        self,
+        messages: list[LLMMessage],
+        *,
+        tools: list[ToolSpec] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[LLMChunk]:
+        params: dict[str, Any] = {
+            "model": self.model,
+            "messages": _to_openai_messages(messages),
+            "temperature": temperature,
+            "stream": True,
+            "stream_options": {"include_usage": True},
+        }
+        if max_tokens is not None:
+            params["max_tokens"] = max_tokens
+        if tools:
+            params["tools"] = _to_openai_tools(tools)
+        params.update(kwargs)
+
+        try:
+            stream = await self.client.chat.completions.create(**params)
+            async for ev in stream:
+                if not ev.choices:
+                    # 最终 usage chunk (choices 为空, 只有 usage)
+                    if getattr(ev, "usage", None):
+                        yield LLMChunk(
+                            content="",
+                            finish_reason="stop",
+                            usage={
+                                "prompt_tokens": ev.usage.prompt_tokens,
+                                "completion_tokens": ev.usage.completion_tokens,
+                                "total_tokens": ev.usage.total_tokens,
+                            },
+                        )
+                    continue
+                choice = ev.choices[0]
+                delta = choice.delta
+                tc_dumps: list[dict[str, Any]] = []
+                if delta.tool_calls:
+                    for tc in delta.tool_calls:
+                        tc_dumps.append(tc.model_dump(exclude_unset=True))
+                yield LLMChunk(
+                    content=delta.content or "",
+                    tool_calls=tc_dumps,
+                    finish_reason=choice.finish_reason,
+                )
+        except (APITimeoutError, RateLimitError, APIError) as e:
+            logger.warning("LLM stream retry: %s", e)
+            raise
+        except Exception as e:
+            raise LLMUnavailableError(
+                f"LLM stream failed: {e}", retryable=False
+            ) from e
+
+    async def health_check(self) -> bool:
+        """极简探活: 1 token 补全."""
+        try:
+            resp = await self.client.chat.completions.create(
+                model=self.model,
+                messages=[{"role": "user", "content": "ping"}],
+                max_tokens=1,
+                temperature=0,
+            )
+            return bool(resp.choices)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("LLM health check failed: %s", e)
+            return False
+
+
+# 向后兼容别名: 早期代码可能用 MiniMaxLLM
+MiniMaxLLM = OpenAICompatibleLLM

app/main.py

@@ -0,0 +1,131 @@
+"""FastAPI 应用入口.
+
+启动顺序 (lifespan):
+1. setup_logging
+2. restore_from_hf  (持久化恢复, 失败不阻塞)
+3. (阶段 2 接入) Chroma client, BGE-M3, reranker 预热
+4. (阶段 3 接入) LangGraph checkpointer 初始化
+
+关闭顺序:
+1. (阶段 3 接入) flush LangGraph checkpoint
+2. push_to_hf  (持久化推送)
+3. close_llm  (关闭 LLM httpx client)
+"""
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app import __version__
+from app.agents.graph import close_checkpointer, get_compiled_graph
+from app.api import chat, documents, health, sessions
+from app.config import settings
+from app.core.errors import install_exception_handlers
+from app.core.logging import setup_logging
+from app.deps import close_llm
+from app.models import db as app_db
+from app.services.embedding import warm_up as warm_embedder
+from app.services.persist import push_to_hf, restore_from_hf
+from app.services.reranker import warm_up as warm_reranker
+from app.services.vector_store import get_chroma
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # ===== Startup =====
+    setup_logging()
+    logger.info("=" * 60)
+    logger.info("Starting %s v%s", settings.app_name, __version__)
+    logger.info("LLM provider: %s | model: %s", settings.llm_provider, settings.minimax_model)
+    logger.info("Data dir: %s", settings.data_dir)
+    logger.info("Allowed origins: %s", settings.allowed_origins)
+
+    # 持久化恢复 (不阻塞)
+    await restore_from_hf()
+
+    # SQLite schema (元数据 + LangGraph checkpoint 共用 db)
+    app_db.init_db()
+
+    # Chroma 客户端 (建立 collection)
+    try:
+        get_chroma()
+        logger.info("ChromaDB ready")
+    except Exception as e:  # noqa: BLE001
+        logger.warning("ChromaDB init failed (will retry on first request): %s", e)
+
+    # BGE-M3 & Reranker 预热.
+    # 必须在主线程 *同步* 执行, 不能 run_in_executor 异步跑 — 因为 FlagEmbedding
+    # 在 torch 2.2 + transformers 4.57 组合下, 子线程首次 .to(device) 会撞 meta tensor
+    # 错 "Cannot copy out of meta tensor; no data!"; 必须等它 meta→cpu 转移完再 await
+    import os
+    if settings.embedding_model and not os.environ.get("TESTING"):
+        try:
+            warm_embedder()
+            warm_reranker()
+        except Exception as e:  # noqa: BLE001
+            logger.warning("Embedder/reranker warm-up failed: %s", e)
+
+    # LangGraph checkpointer 初始化 (不预热, 首次 chat 才编译)
+    try:
+        # 仅检查 import 路径, 不实际编译
+        from app.agents.graph import _build_graph  # noqa: F401
+        logger.info("LangGraph importable")
+    except Exception as e:  # noqa: BLE001
+        logger.warning("LangGraph import failed: %s", e)
+
+    logger.info("Backend ready")
+    yield
+
+    # ===== Shutdown =====
+    logger.info("Shutting down...")
+    try:
+        await push_to_hf()
+    except Exception as e:  # noqa: BLE001
+        logger.warning("Final persist push failed: %s", e)
+    await close_checkpointer()
+    await close_llm()
+    logger.info("Bye")
+
+
+app = FastAPI(
+    title="AI Chatbot",
+    version=__version__,
+    lifespan=lifespan,
+    docs_url="/api/docs",
+    redoc_url="/api/redoc",
+    openapi_url="/api/openapi.json",
+)
+
+# CORS (个人使用, 信任 GH Pages 域 + 本地)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.allowed_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+    expose_headers=["*"],
+)
+
+# 异常处理
+install_exception_handlers(app)
+
+# 路由
+app.include_router(health.router, prefix="/api/v1")
+app.include_router(chat.router, prefix="/api/v1")
+app.include_router(documents.router, prefix="/api/v1")
+app.include_router(sessions.router, prefix="/api/v1")
+
+
+@app.get("/", include_in_schema=False)
+async def root() -> dict:
+    return {
+        "name": settings.app_name,
+        "version": __version__,
+        "llm_provider": settings.llm_provider,
+        "docs": "/api/docs",
+    }

app/models/db.py

@@ -0,0 +1,358 @@
+"""SQLite 元数据 + LangGraph checkpoint 共享 db.
+
+用 sqlite3 stdlib 即可, 暂不引入 SQLAlchemy (减少依赖).
+WAL 模式开启, 允许 LangGraph checkpoint 与文档读并发.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import threading
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Iterator
+
+from app.config import settings
+from app.core.paths import sqlite_dir
+
+logger = logging.getLogger(__name__)
+
+_local = threading.local()
+
+
+def _connect() -> sqlite3.Connection:
+    """每线程一个连接 (sqlite3 本身不线程安全)."""
+    conn = sqlite3.connect(
+        str(settings.sqlite_db_path),
+        check_same_thread=False,
+        isolation_level=None,  # autocommit, 手动 BEGIN
+        timeout=30.0,
+    )
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=NORMAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    return conn
+
+
+def get_conn() -> sqlite3.Connection:
+    """获取当前线程的连接."""
+    conn = getattr(_local, "conn", None)
+    if conn is None:
+        conn = _connect()
+        _local.conn = conn
+    return conn
+
+
+@contextmanager
+def transaction() -> Iterator[sqlite3.Connection]:
+    """显式事务 wrapper."""
+    conn = get_conn()
+    conn.execute("BEGIN")
+    try:
+        yield conn
+    except Exception:
+        conn.execute("ROLLBACK")
+        raise
+    else:
+        conn.execute("COMMIT")
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS documents (
+    id              TEXT PRIMARY KEY,
+    filename        TEXT NOT NULL,
+    mime            TEXT,
+    size            INTEGER NOT NULL,
+    page_count      INTEGER,
+    chunk_count     INTEGER DEFAULT 0,
+    status          TEXT NOT NULL DEFAULT 'uploading',
+    progress        INTEGER DEFAULT 0,         -- 0-100, 用于前端进度条
+    progress_label  TEXT,                       -- "正在分块 (12/48)..." 等
+    error           TEXT,
+    sha256          TEXT NOT NULL,
+    parser          TEXT,
+    chunk_size      INTEGER,
+    chunk_overlap   INTEGER,
+    semantic_chunking      INTEGER DEFAULT 0,
+    contextual_retrieval   INTEGER DEFAULT 0,
+    meta_json       TEXT,
+    created_at      REAL NOT NULL,
+    updated_at      REAL NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_documents_sha ON documents(sha256);
+CREATE INDEX IF NOT EXISTS idx_documents_status ON documents(status);
+
+CREATE TABLE IF NOT EXISTS chunks (
+    id              TEXT PRIMARY KEY,
+    doc_id          TEXT NOT NULL,
+    parent_id       TEXT,
+    chunk_index     INTEGER NOT NULL,
+    text            TEXT NOT NULL,
+    token_count     INTEGER,
+    page_no         INTEGER,
+    heading         TEXT,
+    context_prefix  TEXT,
+    created_at      REAL NOT NULL,
+    FOREIGN KEY (doc_id) REFERENCES documents(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_chunks_doc ON chunks(doc_id);
+CREATE INDEX IF NOT EXISTS idx_chunks_parent ON chunks(parent_id);
+
+CREATE TABLE IF NOT EXISTS sessions (
+    id              TEXT PRIMARY KEY,
+    user_id         TEXT NOT NULL DEFAULT 'default',
+    title           TEXT,
+    message_count   INTEGER DEFAULT 0,
+    created_at      REAL NOT NULL,
+    updated_at      REAL NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+    id              TEXT PRIMARY KEY,
+    session_id      TEXT NOT NULL,
+    role            TEXT NOT NULL,
+    content         TEXT NOT NULL,
+    citations_json  TEXT,
+    tool_calls_json TEXT,
+    created_at      REAL NOT NULL,
+    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, created_at);
+"""
+
+
+def init_db() -> None:
+    """启动时调用. 幂等."""
+    sqlite_dir()
+    conn = get_conn()
+    conn.executescript(SCHEMA)
+    # 在线迁移: 给旧 documents 表加新列 (progress / parser / chunk_size 等).
+    # 失败无害 (列已存在).
+    _MIGRATIONS = [
+        "ALTER TABLE documents ADD COLUMN progress INTEGER DEFAULT 0",
+        "ALTER TABLE documents ADD COLUMN progress_label TEXT",
+        "ALTER TABLE documents ADD COLUMN parser TEXT",
+        "ALTER TABLE documents ADD COLUMN chunk_size INTEGER",
+        "ALTER TABLE documents ADD COLUMN chunk_overlap INTEGER",
+        "ALTER TABLE documents ADD COLUMN semantic_chunking INTEGER DEFAULT 0",
+        "ALTER TABLE documents ADD COLUMN contextual_retrieval INTEGER DEFAULT 0",
+    ]
+    for sql in _MIGRATIONS:
+        try:
+            conn.execute(sql)
+        except Exception:  # noqa: BLE001
+            pass  # 列已存在, 跳过
+    logger.info("DB schema ensured at %s", settings.sqlite_db_path)
+
+
+# ========== Document CRUD ==========
+def doc_insert(doc: dict[str, Any]) -> None:
+    """doc 必须含: id, filename, size, sha256, created_at, updated_at."""
+    conn = get_conn()
+    conn.execute(
+        """
+        INSERT INTO documents (id, filename, mime, size, page_count, chunk_count,
+                               status, progress, progress_label, error, sha256,
+                               parser, chunk_size, chunk_overlap,
+                               semantic_chunking, contextual_retrieval,
+                               meta_json, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            doc["id"], doc["filename"], doc.get("mime"), doc["size"],
+            doc.get("page_count"), doc.get("chunk_count", 0),
+            doc.get("status", "uploading"),
+            doc.get("progress", 0), doc.get("progress_label"),
+            doc.get("error"),
+            doc["sha256"], doc.get("parser"),
+            doc.get("chunk_size"), doc.get("chunk_overlap"),
+            int(bool(doc.get("semantic_chunking", False))),
+            int(bool(doc.get("contextual_retrieval", False))),
+            json.dumps(doc.get("meta", {}), ensure_ascii=False),
+            doc["created_at"], doc.get("updated_at", doc["created_at"]),
+        ),
+    )
+
+
+def doc_update_status(
+    doc_id: str,
+    status: str,
+    *,
+    error: str | None = None,
+    chunk_count: int | None = None,
+    page_count: int | None = None,
+    progress: int | None = None,
+    progress_label: str | None = None,
+) -> None:
+    conn = get_conn()
+    sets = ["status = ?", "updated_at = ?"]
+    params: list[Any] = [status, time.time()]
+    if error is not None:
+        sets.append("error = ?")
+        params.append(error)
+    if chunk_count is not None:
+        sets.append("chunk_count = ?")
+        params.append(chunk_count)
+    if page_count is not None:
+        sets.append("page_count = ?")
+        params.append(page_count)
+    if progress is not None:
+        sets.append("progress = ?")
+        params.append(max(0, min(100, int(progress))))
+    if progress_label is not None:
+        sets.append("progress_label = ?")
+        params.append(progress_label)
+    params.append(doc_id)
+    conn.execute(f"UPDATE documents SET {', '.join(sets)} WHERE id = ?", params)
+
+
+def doc_get(doc_id: str) -> dict[str, Any] | None:
+    row = get_conn().execute("SELECT * FROM documents WHERE id = ?", (doc_id,)).fetchone()
+    return _row_to_doc(row) if row else None
+
+
+def doc_find_by_sha256(sha: str) -> dict[str, Any] | None:
+    row = get_conn().execute(
+        "SELECT * FROM documents WHERE sha256 = ? AND status = 'ready' ORDER BY created_at DESC LIMIT 1",
+        (sha,),
+    ).fetchone()
+    return _row_to_doc(row) if row else None
+
+
+def doc_list(limit: int = 100, offset: int = 0) -> list[dict[str, Any]]:
+    rows = get_conn().execute(
+        "SELECT * FROM documents ORDER BY created_at DESC LIMIT ? OFFSET ?",
+        (limit, offset),
+    ).fetchall()
+    return [_row_to_doc(r) for r in rows]
+
+
+def doc_delete(doc_id: str) -> bool:
+    cur = get_conn().execute("DELETE FROM documents WHERE id = ?", (doc_id,))
+    return cur.rowcount > 0
+
+
+def _row_to_doc(row: sqlite3.Row) -> dict[str, Any]:
+    d = dict(row)
+    if d.get("meta_json"):
+        try:
+            d["meta"] = json.loads(d["meta_json"])
+        except json.JSONDecodeError:
+            d["meta"] = {}
+    d.pop("meta_json", None)
+    # 拆出 boolean 字段, 方便前端直接使用
+    d["semantic_chunking"] = bool(d.get("semantic_chunking"))
+    d["contextual_retrieval"] = bool(d.get("contextual_retrieval"))
+    return d
+
+
+# ========== Chunk CRUD (用于上下文回查, 实际检索走 Chroma) ==========
+def chunk_insert_bulk(chunks: list[dict[str, Any]]) -> None:
+    if not chunks:
+        return
+    conn = get_conn()
+    with transaction():
+        conn.executemany(
+            """
+            INSERT OR REPLACE INTO chunks
+            (id, doc_id, parent_id, chunk_index, text, token_count, page_no, heading, context_prefix, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            [
+                (
+                    c["id"], c["doc_id"], c.get("parent_id"), c["chunk_index"],
+                    c["text"], c.get("token_count"), c.get("page_no"),
+                    c.get("heading"), c.get("context_prefix"), c.get("created_at", time.time()),
+                )
+                for c in chunks
+            ],
+        )
+
+
+def chunk_get_by_doc(doc_id: str, limit: int = 200) -> list[dict[str, Any]]:
+    rows = get_conn().execute(
+        "SELECT * FROM chunks WHERE doc_id = ? ORDER BY chunk_index LIMIT ?",
+        (doc_id, limit),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def chunk_delete_by_doc(doc_id: str) -> int:
+    cur = get_conn().execute("DELETE FROM chunks WHERE doc_id = ?", (doc_id,))
+    return cur.rowcount
+
+
+# ========== Session / Message CRUD (阶段 3 实际使用) ==========
+def session_upsert(session_id: str, user_id: str = "default", title: str | None = None) -> None:
+    now = time.time()
+    conn = get_conn()
+    conn.execute(
+        """
+        INSERT INTO sessions (id, user_id, title, message_count, created_at, updated_at)
+        VALUES (?, ?, ?, 0, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET updated_at = excluded.updated_at
+        """,
+        (session_id, user_id, title, now, now),
+    )
+
+
+def session_list(limit: int = 50) -> list[dict[str, Any]]:
+    rows = get_conn().execute(
+        "SELECT * FROM sessions ORDER BY updated_at DESC LIMIT ?", (limit,)
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def session_get(session_id: str) -> dict[str, Any] | None:
+    row = get_conn().execute("SELECT * FROM sessions WHERE id = ?", (session_id,)).fetchone()
+    return dict(row) if row else None
+
+
+def session_delete(session_id: str) -> bool:
+    cur = get_conn().execute("DELETE FROM sessions WHERE id = ?", (session_id,))
+    return cur.rowcount > 0
+
+
+def message_insert(msg: dict[str, Any]) -> None:
+    now = msg.get("created_at", time.time())
+    conn = get_conn()
+    with transaction():
+        conn.execute(
+            """
+            INSERT INTO messages (id, session_id, role, content, citations_json, tool_calls_json, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                msg["id"], msg["session_id"], msg["role"], msg["content"],
+                json.dumps(msg.get("citations", []), ensure_ascii=False),
+                json.dumps(msg.get("tool_calls", []), ensure_ascii=False),
+                now,
+            ),
+        )
+        # 更新 session 计数
+        conn.execute(
+            "UPDATE sessions SET message_count = message_count + 1, updated_at = ? WHERE id = ?",
+            (now, msg["session_id"]),
+        )
+
+
+def message_list_by_session(session_id: str, limit: int = 200) -> list[dict[str, Any]]:
+    rows = get_conn().execute(
+        "SELECT * FROM messages WHERE session_id = ? ORDER BY created_at LIMIT ?",
+        (session_id, limit),
+    ).fetchall()
+    out = []
+    for r in rows:
+        d = dict(r)
+        for k in ("citations_json", "tool_calls_json"):
+            v = d.pop(k, None)
+            if v:
+                try:
+                    d[k.removesuffix("_json")] = json.loads(v)
+                except json.JSONDecodeError:
+                    d[k.removesuffix("_json")] = []
+        out.append(d)
+    return out

app/models/schemas.py

@@ -0,0 +1,100 @@
+"""Pydantic IO schemas (API 请求/响应/事件)."""
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+# ========== Chat ==========
+class ChatRequest(BaseModel):
+    """非流式 / 流式聊天共用请求体."""
+
+    session_id: str = Field(default="default", description="会话 ID, 用于 LangGraph checkpoint 隔离")
+    message: str = Field(..., min_length=1, max_length=8000)
+    # 预留: 未来可加 doc_id 白名单 / 工具开关
+    doc_ids: list[str] | None = None
+    locale: Literal["zh", "en"] = "zh"
+
+
+class ChatResponse(BaseModel):
+    """非流式响应."""
+
+    session_id: str
+    message_id: str
+    content: str
+    citations: list[dict[str, Any]] = Field(default_factory=list)
+    agent_steps: list[dict[str, Any]] = Field(default_factory=list)
+    usage: dict[str, int] = Field(default_factory=dict)
+    total_ms: int = 0
+
+
+# ========== Documents ==========
+class DocumentMeta(BaseModel):
+    id: str
+    filename: str
+    mime: str
+    size: int
+    page_count: int | None = None
+    chunk_count: int = 0
+    status: Literal["uploading", "parsing", "embedding", "ready", "failed"] = "uploading"
+    progress: int = 0
+    progress_label: str | None = None
+    error: str | None = None
+    created_at: float
+    sha256: str | None = None
+    parser: str | None = None
+    chunk_size: int | None = None
+    chunk_overlap: int | None = None
+    semantic_chunking: bool = False
+    contextual_retrieval: bool = False
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class DocumentChunk(BaseModel):
+    id: str
+    doc_id: str
+    parent_id: str | None = None
+    chunk_index: int
+    text: str
+    token_count: int | None = None
+    page_no: int | None = None
+    heading: str | None = None
+    context_prefix: str | None = None
+    created_at: float
+
+
+class IngestResult(BaseModel):
+    doc_id: str
+    chunk_count: int
+    status: Literal["ready", "duplicate"] = "ready"
+
+
+# ========== Sessions ==========
+class SessionMeta(BaseModel):
+    id: str
+    title: str | None = None
+    message_count: int = 0
+    created_at: float
+    updated_at: float
+
+
+# ========== Health ==========
+class HealthStatus(BaseModel):
+    status: Literal["ok", "degraded"]
+    llm: bool
+    persist: dict[str, Any]
+    chroma: bool = False
+    version: str
+
+
+# ========== Streaming events (AG-UI 兼容) ==========
+class StreamEvent(BaseModel):
+    """统一的 SSE 事件 envelope. 序列化为 `event: <type>\\ndata: <json>\\n\\n`."""
+
+    type: Literal[
+        "thinking", "agent_step", "retrieval", "tool_call",
+        "token", "citation", "progress", "done", "error",
+    ]
+    data: dict[str, Any] = Field(default_factory=dict)
+    ts: float = Field(default_factory=lambda: __import__("time").time())

app/services/chunking.py

@@ -0,0 +1,291 @@
+"""层次化分块器.
+
+策略:
+1. 优先按 markdown 标题拆分 (H1/H2/H3)
+2. 每个 section 内:
+   - 段间按 token 预算合并 (parent: 1500-2000t)
+   - 段内进一步切分 (child: 400-512t)
+3. 可选: 语义分块 (按 sentence 相似度二次切)
+4. 可选: Anthropic-style 上下文预置 (LLM 给每个 chunk 加 context prefix)
+
+输出:
+- parents: 大块, 给 LLM 喂上下文用
+- children: 小块, 给向量检索用
+- 每个 child 带 parent_id, page_no, heading 字段
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import time
+import uuid
+from dataclasses import dataclass, field
+
+from app.config import settings
+from app.llm.base import LLMMessage
+from app.services.parsers.base_parser import ParsedDocument
+
+logger = logging.getLogger(__name__)
+
+
+# 标题正则 (markdown)
+_HEADING_RE = re.compile(r"^(#{1,6})\s+(.+?)\s*$", re.MULTILINE)
+
+
+@dataclass
+class Chunk:
+    """分块结果 (child or parent)."""
+
+    id: str
+    doc_id: str
+    parent_id: str | None
+    chunk_index: int
+    text: str
+    token_count: int
+    page_no: int | None = None
+    heading: str | None = None
+    context_prefix: str | None = None
+    created_at: float = field(default_factory=time.time)
+
+
+def _approx_token_count(s: str) -> int:
+    """粗估 token 数. 用 chars/2 当近似, 避免引 tiktoken."""
+    if not s:
+        return 0
+    # 中英文混合: CJK 算 1.5 token/char, 其它算 0.5
+    cjk = sum(1 for c in s if "一" <= c <= "鿿")
+    other = len(s) - cjk
+    return int(cjk * 1.5 + other * 0.5)
+
+
+def _split_by_headings(markdown: str) -> list[tuple[str, str]]:
+    """按 markdown 标题拆分. 返回 [(heading, body), ...].
+
+    heading 为 None 表示标题前的引言段.
+    """
+    matches = list(_HEADING_RE.finditer(markdown))
+    if not matches:
+        return [(None, markdown)]
+
+    chunks: list[tuple[str, str]] = []
+    # 引言段
+    pre = markdown[: matches[0].start()].strip()
+    if pre:
+        chunks.append((None, pre))
+
+    for i, m in enumerate(matches):
+        heading = m.group(2).strip()
+        start = m.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(markdown)
+        body = markdown[start:end].strip()
+        if body:
+            chunks.append((heading, body))
+    return chunks
+
+
+def _sliding_window(text: str, target: int, overlap: int) -> list[str]:
+    """按 token 估值的滑动窗口切分.
+
+    简化版: 按段落切, 累积到 target token 就 flush, 与上一段重叠 overlap.
+    """
+    paragraphs = [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()]
+    if not paragraphs:
+        return []
+
+    pieces: list[str] = []
+    buf: list[str] = []
+    buf_tokens = 0
+    for p in paragraphs:
+        pt = _approx_token_count(p)
+        # 单段超过 target, 硬切
+        if pt > target:
+            if buf:
+                pieces.append("\n\n".join(buf))
+                buf, buf_tokens = [], 0
+            # 字符级切
+            step = max(int(target * 2), 200)  # target * 2 chars ≈ target tokens
+            for i in range(0, len(p), step):
+                pieces.append(p[i : i + step])
+            continue
+        if buf_tokens + pt > target and buf:
+            pieces.append("\n\n".join(buf))
+            # overlap: 保留最后一段
+            if overlap > 0 and buf:
+                last = buf[-1]
+                last_t = _approx_token_count(last)
+                if last_t <= overlap:
+                    buf = [last]
+                    buf_tokens = last_t
+                else:
+                    buf, buf_tokens = [], 0
+            else:
+                buf, buf_tokens = [], 0
+        buf.append(p)
+        buf_tokens += pt
+    if buf:
+        pieces.append("\n\n".join(buf))
+    return pieces
+
+
+def _split_by_paragraphs(text: str) -> list[str]:
+    return [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()]
+
+
+@dataclass
+class ChunkingResult:
+    parents: list[Chunk]
+    children: list[Chunk]
+
+
+def chunk_document(parsed: ParsedDocument, doc_id: str) -> ChunkingResult:
+    """对 ParsedDocument 做层次化分块.
+
+    步骤:
+    1. 按 markdown 标题分 section
+    2. 每个 section 用滑动窗口切 parent (2000t, overlap 200)
+    3. 每个 parent 内用滑动窗口切 child (512t, overlap 64)
+    4. 按 page 编号 (按 parent 在 markdown 中的字符位置近似)
+    """
+    md = parsed.markdown
+    sections = _split_by_headings(md)
+    page_text = parsed.pages  # 可能为空 (Marker)
+
+    parents: list[Chunk] = []
+    children: list[Chunk] = []
+    chunk_idx = 0
+
+    for heading, body in sections:
+        # 先切 parent
+        for ptext in _sliding_window(body, target=2000, overlap=200):
+            pid = uuid.uuid4().hex
+            ptoks = _approx_token_count(ptext)
+            # 估算 page_no
+            page_no = _estimate_page_no(ptext, parsed) if page_text else None
+            parent = Chunk(
+                id=pid,
+                doc_id=doc_id,
+                parent_id=None,
+                chunk_index=chunk_idx,
+                text=ptext,
+                token_count=ptoks,
+                page_no=page_no,
+                heading=heading,
+            )
+            parents.append(parent)
+            chunk_idx += 1
+
+            # 切 child
+            for ctext in _sliding_window(ptext, target=settings.chunk_size, overlap=settings.chunk_overlap):
+                cid = uuid.uuid4().hex
+                ctoks = _approx_token_count(ctext)
+                child = Chunk(
+                    id=cid,
+                    doc_id=doc_id,
+                    parent_id=pid,
+                    chunk_index=chunk_idx,
+                    text=ctext,
+                    token_count=ctoks,
+                    page_no=page_no,
+                    heading=heading,
+                )
+                children.append(child)
+                chunk_idx += 1
+
+    return ChunkingResult(parents=parents, children=children)
+
+
+def _estimate_page_no(snippet: str, parsed: ParsedDocument) -> int | None:
+    """在 parsed.pages 里找包含 snippet 片段的页. 简单字符串包含."""
+    if not parsed.pages:
+        return None
+    # 取 snippet 前 50 字符作锚
+    anchor = snippet[:50].strip()
+    if not anchor:
+        return None
+    for p in parsed.pages:
+        if anchor in p.text:
+            return p.page_no
+    return None
+
+
+# ========== 上下文预置 (Anthropic-style) ==========
+_CONTEXT_PROMPT_TEMPLATE = (
+    "你是一名文档分块上下文标注助手。给定一段来自文档的 chunk (用 <chunk> 包裹) "
+    "以及文档标题, 请用 1-2 句中文描述该 chunk 在整篇文档中的上下文, 帮助后续检索时理解其含义。\n\n"
+    "要求:\n"
+    "- 简洁, 不超过 80 字\n"
+    "- 包含: 这是什么类型的内容 (定义 / 例子 / 数据 / 结论 / 步骤等), 在文档哪个章节\n"
+    "- 不要重复 chunk 原内容\n"
+    "- 仅输出描述本身, 不要加任何前缀\n\n"
+    "文档标题: {doc_title}\n"
+    "所属章节: {heading}\n"
+    "<chunk>\n{chunk}\n</chunk>\n\n"
+    "上下文描述:"
+)
+
+
+async def contextualize_chunks(
+    chunks: list[Chunk],
+    *,
+    doc_title: str = "未知文档",
+    max_concurrency: int = 4,
+) -> list[Chunk]:
+    """为每个 chunk 生成 context_prefix. Anthropic-style.
+
+    优化:
+    - 并发限流 (max_concurrency), 不爆 LLM 限流
+    - 失败容错: 单条失败不中断, 留 prefix=None
+    """
+    if not settings.contextual_retrieval or not chunks:
+        return chunks
+
+    try:
+        from app.llm.factory import get_llm
+    except Exception as e:  # noqa: BLE001
+        logger.warning("LLM not available for contextual retrieval: %s", e)
+        return chunks
+
+    sem = asyncio.Semaphore(max_concurrency)
+
+    async def _one(c: Chunk) -> None:
+        if c.context_prefix:
+            return
+        async with sem:
+            try:
+                llm = get_llm()
+                prompt = _CONTEXT_PROMPT_TEMPLATE.format(
+                    doc_title=doc_title,
+                    heading=c.heading or "无",
+                    chunk=c.text[:1200],  # 限长, 防 LLM token 爆
+                )
+                resp = await llm.chat(
+                    messages=[
+                        LLMMessage(role="system", content="你是上下文标注助手。"),
+                        LLMMessage(role="user", content=prompt),
+                    ],
+                    temperature=0.2,
+                    max_tokens=160,
+                )
+                prefix = (resp.content or "").strip().strip('"').strip("'")
+                if len(prefix) > 200:
+                    prefix = prefix[:200]
+                c.context_prefix = prefix or None
+            except Exception as e:  # noqa: BLE001
+                logger.warning("Contextual retrieval failed for chunk %s: %s", c.id[:8], e)
+
+    await asyncio.gather(*[_one(c) for c in chunks])
+    n_ok = sum(1 for c in chunks if c.context_prefix)
+    logger.info("Contextualized %d/%d chunks", n_ok, len(chunks))
+    return chunks
+
+
+def chunk_to_embed_text(c: Chunk) -> str:
+    """向量化用的文本: context_prefix + heading + body."""
+    parts: list[str] = []
+    if c.context_prefix:
+        parts.append(f"[Context: {c.context_prefix}]")
+    if c.heading:
+        parts.append(f"[Section: {c.heading}]")
+    parts.append(c.text)
+    return "\n".join(parts)

app/services/embedding.py

@@ -0,0 +1,174 @@
+"""BGE-M3 嵌入服务.
+
+BGE-M3 单模型产出三路表示 (FlagEmbedding 库):
+- dense_vecs: 1024 维稠密向量 (语义)
+- lexical_weights: SPLADE 风格稀疏权重 (精确词命中)
+- colbert_vecs: 多向量 (每 token 一个 1024 维) (late interaction)
+
+设计:
+- 全局单例 BGEM3FlagModel (首次调用懒加载)
+- encode() 异步, 内部走线程池 (CPU 密集)
+- encode_query() 给单 query 用, 自动加 instruction prefix
+- 三路可独立开关 (ColBERT 占内存, 16GB RAM 下建议可降级)
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from functools import lru_cache
+from typing import Any
+
+import numpy as np
+
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+# BGE-M3 query instruction (BAAI 官方推荐)
+_QUERY_INSTRUCTION = (
+    "Represent this sentence for searching relevant passages: "
+)
+
+
+@lru_cache(maxsize=1)
+def get_bge_model():
+    """懒加载 BGE-M3. CPU 上 fp16 自动降级为 fp32."""
+    from FlagEmbedding import BGEM3FlagModel
+
+    # CPU 上强制 fp32, 因为 FlagEmbedding 1.x 在 CPU + fp16 有数值问题
+    use_fp16 = settings.use_fp16 and settings.embedding_device in ("cuda", "mps")
+    logger.info(
+        "Loading BGE-M3: model=%s device=%s fp16=%s",
+        settings.embedding_model,
+        settings.embedding_device,
+        use_fp16,
+    )
+    model = BGEM3FlagModel(
+        settings.embedding_model,
+        use_fp16=use_fp16,
+        device=settings.embedding_device,
+        cache_dir=str(settings.hf_cache_dir),
+    )
+    # 立刻跑一次空 encode, 强制完成 meta→cpu 的 device 转移.
+    # 否则 FlagEmbedding.encode 内部的 self.model.to(device) 会撞到 meta tensor 报
+    # "Cannot copy out of meta tensor; no data!" (在 PyTorch 2.2 + transformers 4.57 组合下)
+    try:
+        with __import__("torch").no_grad():
+            model.encode(
+                ["warmup"],
+                return_dense=True,
+                return_sparse=settings.enable_colbert or True,
+                return_colbert_vecs=settings.enable_colbert,
+                batch_size=1,
+                max_length=8,
+            )
+        logger.info("BGE-M3 meta→cpu device transfer done")
+    except Exception as e:  # noqa: BLE001
+        logger.warning("BGE-M3 warmup encode failed (will retry on first real call): %s", e)
+    return model
+
+
+def warm_up() -> None:
+    """在 lifespan 启动时调用, 避免首次请求时的 30s 加载延迟."""
+    try:
+        get_bge_model()
+        logger.info("BGE-M3 warmed up")
+    except Exception as e:  # noqa: BLE001
+        logger.warning("BGE-M3 warm-up failed: %s (will retry on first request)", e)
+
+
+def _normalize_dense(vecs: np.ndarray) -> np.ndarray:
+    """L2 归一化, 余弦相似度 = 点积."""
+    norms = np.linalg.norm(vecs, axis=1, keepdims=True)
+    norms = np.maximum(norms, 1e-12)
+    return vecs / norms
+
+
+class BGEM3Embedder:
+    """BGE-M3 嵌入器, 同时产出 dense / sparse / colbert."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+
+    async def encode(self, texts: list[str]) -> dict[str, Any]:
+        """编码多个文本.
+
+        Returns:
+            {
+              "dense": np.ndarray,    # (N, 1024) 已 L2 归一化
+              "sparse": list[dict],   # [{"token_id": weight, ...}, ...]
+              "colbert": list[np.ndarray],  # [N x (T_i, 1024)]
+            }
+        """
+        if not texts:
+            return {"dense": np.zeros((0, 1024), dtype=np.float32), "sparse": [], "colbert": []}
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self._encode_sync, texts)
+
+    def _encode_sync(self, texts: list[str]) -> dict[str, Any]:
+        model = get_bge_model()
+        with self._lock:
+            out = model.encode(
+                texts,
+                return_dense=True,
+                return_sparse=settings.enable_colbert or True,  # sparse 一直开
+                return_colbert_vecs=settings.enable_colbert,
+                batch_size=12,
+                max_length=512,
+            )
+
+        dense = np.asarray(out["dense_vecs"], dtype=np.float32)
+        dense = _normalize_dense(dense)
+
+        # sparse: FlagEmbedding 返回 dict[token_str -> weight]; 标准化为 {token_id: weight}
+        sparse_list: list[dict[int, float]] = []
+        for sw in out.get("lexical_weights", []):
+            # sw: {token_str: weight} or {token_id(int): weight}
+            # FlagEmbedding 1.2+ 返回 token_id (int)
+            sparse_list.append({int(tid): float(w) for tid, w in sw.items()})
+
+        colbert_list: list[np.ndarray] = []
+        if settings.enable_colbert and "colbert_vecs" in out:
+            for v in out["colbert_vecs"]:
+                colbert_list.append(np.asarray(v, dtype=np.float32))
+
+        return {"dense": dense, "sparse": sparse_list, "colbert": colbert_list}
+
+    async def encode_query(self, query: str) -> dict[str, Any]:
+        """编码单条 query. 加 instruction prefix."""
+        return await self.encode([_QUERY_INSTRUCTION + query])
+
+    # ========== 便利方法 ==========
+    async def encode_dense_only(self, texts: list[str]) -> np.ndarray:
+        """只要 dense, 跳过 sparse/colbert (节省内存/时间)."""
+        if not texts:
+            return np.zeros((0, 1024), dtype=np.float32)
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self._encode_dense_only_sync, texts)
+
+    def _encode_dense_only_sync(self, texts: list[str]) -> np.ndarray:
+        model = get_bge_model()
+        with self._lock:
+            out = model.encode(
+                [_QUERY_INSTRUCTION + t for t in texts],
+                return_dense=True,
+                return_sparse=False,
+                return_colbert_vecs=False,
+                batch_size=12,
+                max_length=512,
+            )
+        dense = np.asarray(out["dense_vecs"], dtype=np.float32)
+        return _normalize_dense(dense)
+
+
+# 全局单例
+_embedder: BGEM3Embedder | None = None
+
+
+def get_embedder() -> BGEM3Embedder:
+    global _embedder
+    if _embedder is None:
+        _embedder = BGEM3Embedder()
+    return _embedder

app/services/ingestion.py

@@ -0,0 +1,319 @@
+"""文档摄入编排器.
+
+完整流水线:
+1. 保存上传文件到 /data/uploads/{doc_id}/{filename}
+2. 计算 SHA256, 查 SQLite 是否有同 sha 的 ready 文档
+   - 有 -> 直接返回 {doc_id, status: "duplicate"}
+3. 解析 (智能路由: primary -> fallback)
+4. 分块 (层次化 + 可选语义 + 可选上下文预置)
+5. 向量化 (BGE-M3 三路)
+6. 入库:
+   - ChromaDB: dense + (colbert)
+   - 旁路: sparse (BM25-style)
+   - SQLite: document 行 + chunk 行
+7. 调度 persist.push 异步同步
+8. 返回 {doc_id, chunk_count, status: "ready"}
+"""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from app.config import settings
+from app.core.errors import IngestionFailedError
+from app.core.paths import upload_dir
+from app.models import db
+from app.models.schemas import IngestResult
+from app.services.chunking import (
+    Chunk,
+    chunk_document,
+    chunk_to_embed_text,
+    contextualize_chunks,
+)
+from app.services.embedding import get_embedder
+from app.services.parsers import parse_with_fallback
+from app.services.parsers.base_parser import ParsedDocument
+from app.services.persist import schedule_push
+from app.services.vector_store import upsert_chunks
+
+logger = logging.getLogger(__name__)
+
+
+# 单并发摄入队列 (避免大 PDF 同时跑爆 RAM)
+_ingest_lock = asyncio.Lock()
+
+
+@dataclass
+class _IngestContext:
+    doc_id: str
+    file_path: Path
+    filename: str
+    mime: str
+    size: int
+    sha256: str
+    started: float
+
+
+async def _save_upload(*, content: bytes, filename: str) -> tuple[Path, str, int, str]:
+    """保存上传字节到 /data/uploads/{doc_id}/{filename}, 返回 (path, mime, size, sha256)."""
+    doc_id = uuid.uuid4().hex
+    dest_dir = upload_dir() / doc_id
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    # 防路径穿越
+    safe_name = Path(filename).name or "upload"
+    dest = dest_dir / safe_name
+    dest.write_bytes(content)
+
+    # MIME 简单嗅探
+    mime = _sniff_mime(safe_name, content[:2048])
+    sha = hashlib.sha256(content).hexdigest()
+    return dest, mime, len(content), sha
+
+
+def _sniff_mime(filename: str, head: bytes) -> str:
+    ext = Path(filename).suffix.lower()
+    return {
+        ".pdf": "application/pdf",
+        ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".tiff": "image/tiff",
+        ".html": "text/html",
+    }.get(ext, "application/octet-stream")
+
+
+async def ingest_bytes(
+    *,
+    content: bytes,
+    filename: str,
+) -> IngestResult:
+    """公开入口. 处理上传的原始字节."""
+    async with _ingest_lock:
+        return await _ingest_locked(content, filename)
+
+
+async def _ingest_locked(content: bytes, filename: str) -> IngestResult:
+    started = time.time()
+    # 1. 保存
+    file_path, mime, size, sha = await _save_upload(content=content, filename=filename)
+    doc_id = file_path.parent.name  # 用 upload 子目录名当 doc_id (一致)
+
+    logger.info("Ingest start: %s (%d bytes, sha=%s)", filename, size, sha[:12])
+
+    # 2. SHA256 幂等检查
+    existing = db.doc_find_by_sha256(sha)
+    if existing is not None:
+        logger.info("Duplicate by sha256: existing doc_id=%s", existing["id"])
+        # 删除刚写入的副本, 复用旧 doc
+        try:
+            file_path.unlink(missing_ok=True)
+        except Exception:  # noqa: BLE001
+            pass
+        return IngestResult(doc_id=existing["id"], chunk_count=existing.get("chunk_count", 0), status="duplicate")
+
+    # 3. 写入 SQLite (状态 uploading -> parsing)
+    db.doc_insert({
+        "id": doc_id,
+        "filename": Path(filename).name,
+        "mime": mime,
+        "size": size,
+        "sha256": sha,
+        "status": "parsing",
+        "progress": 0,
+        "progress_label": "开始解析...",
+        "parser": settings.parser_primary,
+        "chunk_size": settings.chunk_size,
+        "chunk_overlap": settings.chunk_overlap,
+        "semantic_chunking": settings.semantic_chunking,
+        "contextual_retrieval": settings.contextual_retrieval,
+        "created_at": started,
+        "updated_at": started,
+        "meta": {},
+    })
+
+    try:
+        # 4. 解析
+        db.doc_update_status(doc_id, "parsing", progress=10, progress_label="解析 PDF/Word 结构...")
+        parsed = await parse_with_fallback(file_path)
+        page_count = parsed.meta.get("page_count")
+        db.doc_update_status(doc_id, "parsing", page_count=page_count, progress=30, progress_label="解析完成, 准备分块")
+
+        # 5. 分块
+        chunking = chunk_document(parsed, doc_id=doc_id)
+        logger.info(
+            "Chunked: %d parents, %d children for %s",
+            len(chunking.parents), len(chunking.children), filename,
+        )
+        db.doc_update_status(
+            doc_id, "parsing",
+            progress=45,
+            progress_label=f"分块 {len(chunking.children)} 个 chunk",
+        )
+
+        # 6. 上下文预置 (可选, 走 LLM, 慢但提升召回)
+        if settings.contextual_retrieval and chunking.children:
+            db.doc_update_status(
+                doc_id, "embedding",
+                progress=50,
+                progress_label="上下文预标注 (走 LLM)...",
+            )
+            await contextualize_chunks(
+                chunking.children, doc_title=Path(filename).name, max_concurrency=4
+            )
+
+        # 7. 向量化
+        db.doc_update_status(doc_id, "embedding", progress=55, progress_label="向量化中...")
+        embedder = get_embedder()
+        embed_texts = [chunk_to_embed_text(c) for c in chunking.children]
+        if not embed_texts:
+            logger.warning("No chunks to embed for %s", filename)
+            db.doc_update_status(doc_id, "ready", chunk_count=0, progress=100, progress_label="完成 (空文档)")
+            return IngestResult(doc_id=doc_id, chunk_count=0, status="ready")
+
+        # batch 编码
+        BATCH = 32
+        all_dense: list[np.ndarray] = []
+        all_sparse: list[dict[int, float]] = []
+        all_colbert: list[np.ndarray] = []
+        n_total = len(embed_texts)
+        for i in range(0, n_total, BATCH):
+            batch = embed_texts[i : i + BATCH]
+            out = await embedder.encode(batch)
+            all_dense.append(out["dense"])
+            all_sparse.extend(out.get("sparse", []))
+            all_colbert.extend(out.get("colbert", []))
+            done = min(i + BATCH, n_total)
+            # 55% -> 95%
+            pct = 55 + int((done / n_total) * 40)
+            db.doc_update_status(
+                doc_id, "embedding",
+                progress=pct,
+                progress_label=f"向量化 {done}/{n_total}",
+            )
+            logger.info(
+                "Embedded %d/%d chunks", done, n_total
+            )
+
+        dense_arr = np.vstack(all_dense) if all_dense else np.zeros((0, 1024), dtype=np.float32)
+
+        # 8. 入库 ChromaDB + sparse 旁路
+        ids = [c.id for c in chunking.children]
+        documents = [c.text for c in chunking.children]
+        metadatas = [
+            {
+                "doc_id": c.doc_id,
+                "parent_id": c.parent_id or "",
+                "chunk_index": c.chunk_index,
+                "page_no": c.page_no or 0,
+                "heading": c.heading or "",
+                "context_prefix": c.context_prefix or "",
+            }
+            for c in chunking.children
+        ]
+        upsert_chunks(
+            ids=ids,
+            embeddings=dense_arr,
+            documents=documents,
+            metadatas=metadatas,
+            sparse_weights=all_sparse or None,
+            colbert_vecs=all_colbert or None,
+        )
+
+        # 9. 写入 SQLite chunks
+        db.chunk_insert_bulk([
+            {
+                "id": c.id,
+                "doc_id": c.doc_id,
+                "parent_id": c.parent_id,
+                "chunk_index": c.chunk_index,
+                "text": c.text,
+                "token_count": c.token_count,
+                "page_no": c.page_no,
+                "heading": c.heading,
+                "context_prefix": c.context_prefix,
+                "created_at": c.created_at,
+            }
+            for c in chunking.children
+        ])
+
+        # 10. 文档就绪
+        elapsed_ms = int((time.time() - started) * 1000)
+        db.doc_update_status(
+            doc_id, "ready",
+            chunk_count=len(chunking.children),
+            page_count=page_count,
+            progress=100,
+            progress_label="就绪",
+        )
+        logger.info(
+            "Ingest done: %s doc_id=%s chunks=%d %dms",
+            filename, doc_id, len(chunking.children), elapsed_ms,
+        )
+
+        # 11. 调度持久化推送
+        await schedule_push()
+
+        return IngestResult(
+            doc_id=doc_id,
+            chunk_count=len(chunking.children),
+            status="ready",
+        )
+
+    except Exception as e:  # noqa: BLE001
+        logger.exception("Ingest failed for %s", filename)
+        try:
+            db.doc_update_status(doc_id, "failed", error=str(e)[:500])
+        except Exception:  # noqa: BLE001
+            pass
+        raise IngestionFailedError(
+            f"Ingest failed: {e}", code="ingest_failed", detail={"doc_id": doc_id}
+        ) from e
+
+
+async def delete_document(doc_id: str) -> bool:
+    """完整删除: ChromaDB + 旁路 sparse + SQLite + uploads/."""
+    # 先查, 拿文件路径
+    doc = db.doc_get(doc_id)
+    if doc is None:
+        return False
+
+    # 从 ChromaDB / sparse 旁路删
+    try:
+        from app.services.vector_store import delete_by_doc
+        delete_by_doc(doc_id)
+    except Exception as e:  # noqa: BLE001
+        logger.warning("ChromaDB delete failed for %s: %s", doc_id, e)
+
+    # SQLite chunks + document
+    db.chunk_delete_by_doc(doc_id)
+    db.doc_delete(doc_id)
+
+    # 删上传原文件
+    if doc.get("sha256"):
+        # doc_id 即子目录名
+        up_dir = upload_dir() / doc_id
+        if up_dir.exists():
+            import shutil
+            shutil.rmtree(up_dir, ignore_errors=True)
+
+    await schedule_push()
+    return True
+
+
+def list_documents(limit: int = 100) -> list[dict[str, Any]]:
+    return db.doc_list(limit=limit)
+
+
+def get_document(doc_id: str) -> dict[str, Any] | None:
+    return db.doc_get(doc_id)

app/services/llm_cache.py

@@ -0,0 +1,94 @@
+"""LLM 响应缓存 (内存 LRU).
+
+为什么需要:
+- 个人使用场景下, 同一问题反复问很常见
+- 命中时直接跳过 LLM 调用 + 流式回放 token
+- 节省 API 费用 + 缩短延迟
+
+设计:
+- key = sha256( (query + top_doc_ids + temperature) )  -- 只缓存"标准问答", 不缓存工具调用
+- value = 完整回答内容 + 引用 + 工具调用结果
+- LRU 容量可配 (默认 200)
+- 进程内, 重启清空 (避免引入 Redis)
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from cachetools import LRUCache
+
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CachedAnswer:
+    content: str
+    citations: list[dict[str, Any]]
+    tool_calls: list[dict[str, Any]]
+    tokens: list[str]  # 预切好的 token 序列, 流式回放
+
+
+_cache: LRUCache | None = None
+_hits = 0
+_misses = 0
+
+
+def _make_key(query: str, top_doc_ids: list[str], temperature: float) -> str:
+    """缓存 key. 包含 query + 命中文档 id + 温度, 避免不同上下文错命中."""
+    payload = f"{query.strip()}|{','.join(sorted(top_doc_ids))}|{temperature:.2f}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def get_cache() -> LRUCache:
+    global _cache
+    if _cache is None:
+        size = settings.llm_cache_size if settings.llm_cache_enabled else 0
+        _cache = LRUCache(maxsize=size)
+        logger.info("LLM cache initialized: enabled=%s size=%d", settings.llm_cache_enabled, size)
+    return _cache
+
+
+def lookup(query: str, top_doc_ids: list[str], temperature: float) -> CachedAnswer | None:
+    if not settings.llm_cache_enabled:
+        return None
+    key = _make_key(query, top_doc_ids, temperature)
+    hit = get_cache().get(key)
+    global _hits, _misses
+    if hit is not None:
+        _hits += 1
+        logger.debug("LLM cache HIT key=%s", key[:12])
+    else:
+        _misses += 1
+    return hit
+
+
+def store(query: str, top_doc_ids: list[str], temperature: float, answer: CachedAnswer) -> None:
+    if not settings.llm_cache_enabled:
+        return
+    key = _make_key(query, top_doc_ids, temperature)
+    get_cache()[key] = answer
+    logger.debug("LLM cache STORE key=%s tokens=%d", key[:12], len(answer.tokens))
+
+
+def stats() -> dict[str, Any]:
+    return {
+        "enabled": settings.llm_cache_enabled,
+        "size": len(get_cache()),
+        "max_size": get_cache().maxsize,
+        "hits": _hits,
+        "misses": _misses,
+        "hit_rate": (_hits / max(_hits + _misses, 1)),
+    }
+
+
+def clear() -> None:
+    global _cache, _hits, _misses
+    _cache = None
+    _hits = 0
+    _misses = 0
+    logger.info("LLM cache cleared")

app/services/parsers/__init__.py

@@ -0,0 +1,110 @@
+"""Parser 工厂: 智能路由 + 降级链.
+
+智能路由逻辑:
+1. 查 settings.parser_primary (默认 docling)
+2. 主 parser 失败 -> 降级到 settings.parser_fallback
+3. 全部失败 -> 抛 IngestionFailedError
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from app.config import settings
+from app.core.errors import IngestionFailedError
+from app.services.parsers.base_parser import BaseParser, ParsedDocument
+
+logger = logging.getLogger(__name__)
+
+
+# 延迟注册: 实际 import 在 _build_parser 内
+_REGISTRY: dict[str, type[BaseParser]] = {}
+
+
+def _register_default() -> None:
+    """懒加载各 parser. 失败的 (未装) 仅记 warning, 不抛."""
+    if _REGISTRY:
+        return
+    try:
+        from app.services.parsers.docling_parser import DoclingParser
+        _REGISTRY["docling"] = DoclingParser
+    except ImportError as e:
+        logger.warning("docling not installed: %s", e)
+    try:
+        from app.services.parsers.marker_parser import MarkerParser
+        _REGISTRY["marker"] = MarkerParser
+    except ImportError as e:
+        logger.warning("marker-pdf not installed: %s", e)
+    # mineru / vlm 留 hook (按需装)
+
+
+def _build_parser(name: str) -> BaseParser:
+    _register_default()
+    cls = _REGISTRY.get(name)
+    if cls is None:
+        raise IngestionFailedError(
+            f"Parser '{name}' is not installed. pip install docling / marker-pdf.",
+            code="parser_unavailable",
+        )
+    return cls()
+
+
+def get_parser(name: str | None = None) -> BaseParser:
+    """获取单个 parser 实例 (按名字)."""
+    return _build_parser(name or settings.parser_primary)
+
+
+def get_parser_chain() -> list[BaseParser]:
+    """按 settings 配置返回 [primary, fallback] 链."""
+    chain: list[BaseParser] = []
+    for name in (settings.parser_primary, settings.parser_fallback):
+        if name and name not in {p.name for p in chain}:
+            try:
+                chain.append(_build_parser(name))
+            except IngestionFailedError:
+                # 跳过未装的, 继续
+                continue
+    return chain
+
+
+async def parse_with_fallback(file_path: Path) -> ParsedDocument:
+    """按链逐个尝试, 全部失败抛 IngestionFailedError."""
+    chain = get_parser_chain()
+    if not chain:
+        raise IngestionFailedError(
+            "No parser available. Install at least one of: docling, marker-pdf.",
+            code="no_parser_available",
+        )
+
+    # 选能处理该扩展名的 parser
+    candidates = [p for p in chain if p.can_handle(file_path)]
+    if not candidates:
+        raise IngestionFailedError(
+            f"No parser in chain supports {file_path.suffix}",
+            code="unsupported_format",
+            detail={"suffix": file_path.suffix, "chain": [p.name for p in chain]},
+        )
+
+    last_err: Exception | None = None
+    for parser in candidates:
+        try:
+            return await parser.parse(file_path)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("Parser %s failed for %s: %s", parser.name, file_path.name, e)
+            last_err = e
+
+    raise IngestionFailedError(
+        f"All parsers failed for {file_path.name}",
+        code="all_parsers_failed",
+        detail={"chain": [p.name for p in candidates]},
+    ) from last_err
+
+
+__all__ = [
+    "BaseParser",
+    "ParsedDocument",
+    "PageContent",
+    "get_parser",
+    "get_parser_chain",
+    "parse_with_fallback",
+]

app/services/parsers/base_parser.py

@@ -0,0 +1,56 @@
+"""文档解析抽象 + 数据结构.
+
+支持的输入: PDF, DOCX, PNG/JPG (含扫描件).
+
+设计:
+- BaseParser 抽象 parse() -> ParsedDocument
+- ParsedDocument 同时携带 markdown 全文 + 页面级结构 (含表格 / 图片)
+- 各具体 parser (Docling / Marker / MinerU) 实现同一接口, 可热替换
+"""
+from __future__ import annotations
+
+import abc
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class PageContent:
+    """单页内容. 至少要有 text, 可选带 tables / images."""
+
+    page_no: int
+    text: str
+    tables: list[dict] = field(default_factory=list)   # {html, bbox, rows}
+    images: list[dict] = field(default_factory=list)   # {bbox, caption, b64_thumb}
+    headings: list[str] = field(default_factory=list)  # 当前页的标题
+
+
+@dataclass
+class ParsedDocument:
+    """解析后的统一文档结构.
+
+    业务侧只用 markdown (全文) + pages (带页码引用) 两个核心字段.
+    """
+
+    markdown: str                                    # 全文 markdown (LLM 友好)
+    pages: list[PageContent] = field(default_factory=list)
+    tables: list[dict] = field(default_factory=list)  # 全部表格 (跨页表已合并)
+    images: list[dict] = field(default_factory=list)
+    meta: dict = field(default_factory=dict)          # page_count, parser, elapsed_ms, ...
+
+
+class BaseParser(abc.ABC):
+    """文档解析器抽象基类."""
+
+    name: str = "abstract"
+
+    @abc.abstractmethod
+    def supported_extensions(self) -> set[str]:
+        """形如 {'.pdf', '.docx'}."""
+
+    @abc.abstractmethod
+    async def parse(self, file_path: Path) -> ParsedDocument:
+        """同步 IO + 异步 wrapper. 重 CPU 解析可放线程池."""
+
+    def can_handle(self, file_path: Path) -> bool:
+        return file_path.suffix.lower() in self.supported_extensions()

app/services/parsers/docling_parser.py

@@ -0,0 +1,121 @@
+"""Docling parser - 主力.
+
+特性:
+- 结构感知 (reading order / headings)
+- 跨页表合并 (TableFormer)
+- 内置 OCR (PaddleOCR 支持中英)
+- DOCX / PPTX / 图片 / HTML 全支持
+
+Docling API 在 2.x 期间变动较多, 本实现基于 2.30+ 兼容.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from pathlib import Path
+
+from app.config import settings
+from app.services.parsers.base_parser import BaseParser, PageContent, ParsedDocument
+
+logger = logging.getLogger(__name__)
+
+
+class DoclingParser(BaseParser):
+    name = "docling"
+
+    def supported_extensions(self) -> set[str]:
+        return {".pdf", ".docx", ".pptx", ".png", ".jpg", ".jpeg", ".tiff", ".html", ".xlsx"}
+
+    async def parse(self, file_path: Path) -> ParsedDocument:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self._parse_sync, file_path)
+
+    def _parse_sync(self, file_path: Path) -> ParsedDocument:
+        """实际解析. CPU 密集, 在线程池跑."""
+        # Force CPU device for Docling to prevent MPS NotImplementedError on Intel Mac
+        try:
+            import docling.utils.accelerator_utils
+            docling.utils.accelerator_utils.decide_device = lambda *args, **kwargs: "cpu"
+        except ImportError:
+            pass
+
+        # 延迟 import, 避免启动期未装 docling 时崩溃
+        from docling.document_converter import DocumentConverter, PdfFormatOption
+        from docling.datamodel.base_models import InputFormat
+        from docling.datamodel.pipeline_options import PdfPipelineOptions
+
+        started = time.time()
+        logger.info("Docling parsing: %s", file_path.name)
+
+        from docling.datamodel.accelerator_options import AcceleratorOptions, AcceleratorDevice
+        opts = PdfPipelineOptions()
+        opts.do_ocr = settings.parser_enable_ocr
+        opts.do_table_structure = settings.parser_table_structure
+        opts.images_scale = 2.0
+        opts.artifacts_path = str(settings.data_dir / "docling_models")
+        opts.accelerator_options = AcceleratorOptions(device=AcceleratorDevice.CPU)
+
+        converter = DocumentConverter(
+            format_options={
+                InputFormat.PDF: PdfFormatOption(pipeline_options=opts),
+            }
+        )
+
+        try:
+            result = converter.convert(str(file_path))
+        except Exception as e:  # noqa: BLE001
+            logger.exception("Docling parse failed: %s", e)
+            raise
+
+        doc = result.document
+
+        # 全文 markdown
+        markdown = doc.export_to_markdown()
+
+        # 页面级 (Docling 用 iterate_items / pages 属性, 视版本略有差异)
+        pages: list[PageContent] = []
+        try:
+            page_count = len(doc.pages) if hasattr(doc, "pages") else 0
+            for idx in range(page_count):
+                page = doc.pages[idx]
+                # 提取该页文本 (Docling 2.x 没有现成 API, 用 page-level export 近似)
+                page_md = ""
+                if hasattr(page, "export_to_markdown"):
+                    try:
+                        page_md = page.export_to_markdown()
+                    except Exception:  # noqa: BLE001
+                        page_md = ""
+                pages.append(PageContent(
+                    page_no=idx + 1,
+                    text=page_md,
+                    headings=[],  # Docling 不直接给页级 headings, 留空
+                ))
+        except Exception as e:  # noqa: BLE001
+            logger.warning("Docling page extraction partial: %s", e)
+
+        # 表格 (简化提取)
+        tables: list[dict] = []
+        try:
+            for t in (doc.tables or []):
+                tables.append({
+                    "html": t.export_to_html() if hasattr(t, "export_to_html") else "",
+                    "caption": getattr(t, "caption", None),
+                })
+        except Exception:  # noqa: BLE001
+            pass
+
+        elapsed_ms = int((time.time() - started) * 1000)
+        logger.info("Docling done: %s pages, %s tables, %dms", len(pages), len(tables), elapsed_ms)
+
+        return ParsedDocument(
+            markdown=markdown,
+            pages=pages,
+            tables=tables,
+            images=[],
+            meta={
+                "parser": self.name,
+                "page_count": len(pages),
+                "elapsed_ms": elapsed_ms,
+            },
+        )

app/services/parsers/marker_parser.py

@@ -0,0 +1,62 @@
+"""Marker parser - 兜底 (Docling 失败时启用).
+
+特性:
+- PDF -> Markdown 转换, 速度快
+- 内置 surya-ocr, 支持 90+ 语言
+- 不擅长复杂表格 / 跨页表 (不如 Docling), 但胜在稳定
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from pathlib import Path
+
+from app.services.parsers.base_parser import BaseParser, ParsedDocument
+
+logger = logging.getLogger(__name__)
+
+
+class MarkerParser(BaseParser):
+    name = "marker"
+
+    def supported_extensions(self) -> set[str]:
+        # Marker 强项是 PDF; 其它类型建议直接 Docling
+        return {".pdf"}
+
+    async def parse(self, file_path: Path) -> ParsedDocument:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self._parse_sync, file_path)
+
+    def _parse_sync(self, file_path: Path) -> ParsedDocument:
+        # Marker 1.x 推荐用 marker's Python API 而非 CLI subprocess
+        from marker.converters.pdf import PdfConverter
+        from marker.models import create_model_dict
+        from marker.output import text_from_rendered
+
+        started = time.time()
+        logger.info("Marker parsing: %s", file_path.name)
+
+        converter = PdfConverter(artifact_dict=create_model_dict())
+        rendered = converter(str(file_path))
+        markdown, _, _ = text_from_rendered(rendered)
+
+        # Marker 不直接给 page-level 拆分, 走全文 markdown
+        elapsed_ms = int((time.time() - started) * 1000)
+        logger.info("Marker done: %dms", elapsed_ms)
+
+        # 尝试从 rendered 拿 metadata
+        meta = rendered.metadata if hasattr(rendered, "metadata") else {}
+        page_count = meta.get("page_stats", {}).get("total_pages") if isinstance(meta, dict) else None
+
+        return ParsedDocument(
+            markdown=markdown,
+            pages=[],  # Marker 不分页
+            tables=[],
+            images=[],
+            meta={
+                "parser": self.name,
+                "page_count": page_count,
+                "elapsed_ms": elapsed_ms,
+            },
+        )

app/services/persist.py

@@ -0,0 +1,190 @@
+"""HF Dataset repo 持久化同步.
+
+为什么需要: HF Spaces 免费版磁盘是临时的 (容器重启后 /data 内的非持久卷数据会丢).
+唯一免费的持久化方案是把 /data 同步到 HF Dataset repo (Git LFS).
+
+调用模式:
+- lifespan startup: restore_from_hf()
+- 每次写操作后: schedule_push() (异步, 不阻塞用户)
+- lifespan shutdown: push_to_hf() (同步, 尽量)
+
+健壮性:
+- 首次部署 (repo 不存在) → 捕获 RepositoryNotFoundError → 标记 "fresh_start"
+- HF_TOKEN 缺失 → 跳过持久化, 降级为纯本地
+- 网络错误 → 重试 3 次后放弃, 不阻塞业务
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+from pathlib import Path
+from typing import Literal
+
+from huggingface_hub import (
+    create_repo,
+    snapshot_download,
+    upload_folder,
+)
+from huggingface_hub.errors import RepositoryNotFoundError
+
+from app.config import settings
+from app.core.paths import data_dir, sqlite_dir, chroma_dir, upload_dir
+
+logger = logging.getLogger(__name__)
+
+# 状态机: 持久化是否启用 / 启动模式
+_state: dict[str, str | bool] = {
+    "mode": "disabled",  # disabled | cold_restore | fresh_start
+    "last_push_at": 0.0,
+    "pending_push": False,
+}
+
+
+def persist_mode() -> Literal["disabled", "cold_restore", "fresh_start"]:
+    return _state["mode"]  # type: ignore[return-value]
+
+
+async def restore_from_hf() -> None:
+    """从 HF Dataset repo 拉取数据到本地.
+
+    调用时机: FastAPI lifespan 启动.
+    """
+    if not settings.is_persist_enabled():
+        logger.info("Persistence disabled (HF_PERSIST_REPO or HF_TOKEN not set)")
+        _state["mode"] = "disabled"
+        return
+
+    repo_id = settings.hf_persist_repo
+    token = settings.hf_token.get_secret_value()
+    local_root = data_dir()
+    target_subdirs = ["chroma", "sqlite", "uploads"]
+
+    loop = asyncio.get_running_loop()
+    try:
+        await loop.run_in_executor(
+            None,
+            lambda: snapshot_download(
+                repo_id=repo_id,
+                repo_type="dataset",
+                local_dir=str(local_root),
+                token=token,
+                allow_patterns=[f"{d}/*" for d in target_subdirs] + target_subdirs,
+            ),
+        )
+        _state["mode"] = "cold_restore"
+        logger.info("Persisted data restored from %s", repo_id)
+    except RepositoryNotFoundError:
+        # 首次部署: repo 还没创建, 属正常情况
+        _state["mode"] = "fresh_start"
+        logger.info(
+            "Persist repo %s not found (first deploy?). "
+            "Will create on first push.",
+            repo_id,
+        )
+    except Exception as e:  # noqa: BLE001
+        logger.error("Persist restore failed (will start fresh): %s", e)
+        _state["mode"] = "fresh_start"
+        # 不阻塞启动, 提示用户在 /readyz 看到降级状态
+
+
+async def push_to_hf() -> None:
+    """同步推送本地数据到 HF Dataset repo. 阻塞."""
+    if not settings.is_persist_enabled():
+        return
+    if _state["mode"] == "fresh_start":
+        # 首次需要先 create_repo
+        await _ensure_repo_exists()
+
+    repo_id = settings.hf_persist_repo
+    token = settings.hf_token.get_secret_value()
+    local_root = data_dir()
+
+    loop = asyncio.get_running_loop()
+    try:
+        await loop.run_in_executor(
+            None,
+            lambda: upload_folder(
+                folder_path=str(local_root),
+                repo_id=repo_id,
+                repo_type="dataset",
+                token=token,
+                commit_message=f"sync {asyncio.get_running_loop().time():.0f}",
+                ignore_patterns=[".cache/*", "*.tmp", "*.lock"],
+            ),
+        )
+        _state["last_push_at"] = asyncio.get_running_loop().time()
+        _state["pending_push"] = False
+        logger.info("Persisted data pushed to %s", repo_id)
+    except Exception as e:  # noqa: BLE001
+        logger.error("Persist push failed: %s", e)
+
+
+async def schedule_push() -> None:
+    """异步推送, 不阻塞业务. 多次调用合并为一次 (简单去抖).
+
+    适用: 摄入完成 / 删除文档后.
+    """
+    if not settings.is_persist_enabled():
+        return
+    if not settings.persist_on_write:
+        return
+    if _state["pending_push"]:
+        return  # 已有 pending, 跳过
+
+    _state["pending_push"] = True
+
+    async def _delayed_push() -> None:
+        # 简单去抖: 延迟 30s, 把同一秒内的多次写合并
+        await asyncio.sleep(30)
+        if _state["pending_push"]:
+            await push_to_hf()
+
+    asyncio.create_task(_delayed_push())
+
+
+async def _ensure_repo_exists() -> None:
+    """首次部署时自动创建 HF Dataset repo."""
+    repo_id = settings.hf_persist_repo
+    token = settings.hf_token.get_secret_value()
+    loop = asyncio.get_running_loop()
+    try:
+        await loop.run_in_executor(
+            None,
+            lambda: create_repo(
+                repo_id=repo_id,
+                repo_type="dataset",
+                token=token,
+                private=True,
+                exist_ok=True,
+            ),
+        )
+        logger.info("Created persist repo: %s", repo_id)
+    except Exception as e:  # noqa: BLE001
+        logger.error("Failed to create persist repo: %s", e)
+
+
+def persist_status() -> dict:
+    """供 /readyz 暴露持久化状态."""
+    return {
+        "enabled": settings.is_persist_enabled(),
+        "mode": _state["mode"],
+        "pending_push": _state["pending_push"],
+        "repo": settings.hf_persist_repo or None,
+    }
+
+
+def _wipe_local_data() -> None:
+    """测试用: 清空本地 data 目录."""
+    for d in (sqlite_dir(), chroma_dir(), upload_dir()):
+        if d.exists():
+            shutil.rmtree(d, ignore_errors=True)
+
+
+__all__ = [
+    "restore_from_hf",
+    "push_to_hf",
+    "schedule_push",
+    "persist_mode",
+    "persist_status",
+]

app/services/reranker.py

@@ -0,0 +1,107 @@
+"""BGE-reranker-v2-m3 精排服务.
+
+输入: query + list[RetrievalHit]
+输出: 同长度 list, 按相关性分数重排, 返回 top_n
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from functools import lru_cache
+
+from app.config import settings
+from app.services.vector_store import RetrievalHit
+
+logger = logging.getLogger(__name__)
+
+
+@lru_cache(maxsize=1)
+def get_reranker():
+    """懒加载 FlagReranker. CPU 上 fp16 强制 fp32."""
+    from FlagEmbedding import FlagReranker
+
+    use_fp16 = settings.use_fp16 and settings.embedding_device in ("cuda", "mps")
+    logger.info(
+        "Loading reranker: model=%s device=%s fp16=%s",
+        settings.reranker_model, settings.embedding_device, use_fp16,
+    )
+    model = FlagReranker(
+        settings.reranker_model,
+        use_fp16=use_fp16,
+        device=settings.embedding_device,
+        cache_dir=str(settings.hf_cache_dir),
+    )
+    # 预热一次 compute_score, 强制 meta→cpu device 转移 (避免后续 "Cannot copy out of meta tensor")
+    try:
+        with __import__("torch").no_grad():
+            model.compute_score([["warmup query", "warmup passage"]], normalize=True)
+        logger.info("Reranker meta→cpu device transfer done")
+    except Exception as e:  # noqa: BLE001
+        logger.warning("Reranker warmup failed: %s", e)
+    return model
+
+
+def warm_up() -> None:
+    try:
+        get_reranker()
+        logger.info("Reranker warmed up")
+    except Exception as e:  # noqa: BLE001
+        logger.warning("Reranker warm-up failed: %s", e)
+
+
+class RerankerService:
+    """封装 Reranker, 异步 + 限流 + 截断长文本."""
+
+    _sem = None  # 全局信号量, 避免并发打爆 CPU
+
+    def __init__(self, max_concurrency: int = 2) -> None:
+        if RerankerService._sem is None:
+            RerankerService._sem = asyncio.Semaphore(max_concurrency)
+
+    async def rerank(
+        self,
+        query: str,
+        hits: list[RetrievalHit],
+        top_n: int | None = None,
+        max_length: int = 512,
+    ) -> list[RetrievalHit]:
+        """对 hits 按 query 相关性重排, 返回 top_n. 原顺序保留在 original_rank."""
+        if not hits:
+            return []
+        top_n = top_n or settings.rerank_top_n
+
+        # 截断过长的 text (BGE-reranker max 512 token)
+        pairs = [[query, (h.text or "")[: max_length * 2]] for h in hits]
+
+        loop = asyncio.get_running_loop()
+        scores = await loop.run_in_executor(None, self._rerank_sync, pairs)
+
+        # 记 original_rank + 新分数
+        for h, s in zip(hits, scores):
+            h.original_rank = hits.index(h)
+            h.rerank_score = float(s)
+
+        # 按 rerank_score 降序
+        reranked = sorted(hits, key=lambda h: h.rerank_score, reverse=True)
+        return reranked[:top_n]
+
+    def _rerank_sync(self, pairs: list[list[str]]) -> list[float]:
+        model = get_reranker()
+        # FlagReranker.compute_score 直接吃 list[list[str]]
+        scores = model.compute_score(pairs, normalize=True)
+        # 单条输入时返回 float, 统一为 list
+        if isinstance(scores, (int, float)):
+            scores = [float(scores)]
+        return [float(s) for s in scores]
+
+
+# 进程内单例
+_reranker: RerankerService | None = None
+
+
+def get_reranker_service() -> RerankerService:
+    global _reranker
+    if _reranker is None:
+        _reranker = RerankerService()
+    return _reranker

app/services/vector_store.py

@@ -0,0 +1,372 @@
+"""向量存储 + 混合检索.
+
+ChromaDB v1.0 (Rust core) multi-vector 集合:
+- 同一 collection 同时存 dense (1024d) + ColBERT (变长多向量)
+- sparse 走旁路 BM25-style (用 BGE-M3 产出的 lexical weights 反序列化)
+
+混合检索 (三路 RRF):
+- dense 走 ChromaDB HNSW
+- sparse 走反序列化 + dot product
+- colbert 走 late interaction max-sim
+- 三路结果 RRF 融合
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from app.config import settings
+from app.core.paths import chroma_dir, sqlite_dir
+from app.models import db
+
+logger = logging.getLogger(__name__)
+
+
+# ========== 检索结果 ==========
+@dataclass
+class RetrievalHit:
+    chunk_id: str
+    doc_id: str
+    text: str
+    score: float
+    page_no: int | None
+    heading: str | None
+    context_prefix: str | None
+    meta: dict[str, Any]
+    # 用于 CRAG evaluate
+    sparse_score: float = 0.0
+    dense_score: float = 0.0
+    colbert_score: float = 0.0
+    # rerank 后填充
+    rerank_score: float = 0.0
+    original_rank: int = 0
+
+
+# ========== Sparse 旁路索引 (SQLite) ==========
+class SparseSidecar:
+    """存 sparse lexical weights, 用 sqlite 反查 + 打分.
+
+    表 schema: chunk_sparse(chunk_id, weights_json)
+    """
+
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = db_path
+        self._lock = threading.Lock()
+        self._ensure_table()
+
+    def _ensure_table(self) -> None:
+        with db.transaction() as _:
+            db.get_conn().execute(
+                """
+                CREATE TABLE IF NOT EXISTS chunk_sparse (
+                    chunk_id     TEXT PRIMARY KEY,
+                    weights_json TEXT NOT NULL
+                )
+                """
+            )
+
+    def upsert_bulk(self, items: list[tuple[str, dict[int, float]]]) -> None:
+        if not items:
+            return
+        with self._lock, db.transaction():
+            db.get_conn().executemany(
+                "INSERT OR REPLACE INTO chunk_sparse (chunk_id, weights_json) VALUES (?, ?)",
+                [(cid, json.dumps({str(k): v for k, v in w.items()})) for cid, w in items],
+            )
+
+    def upsert_colbert(self, items: list[tuple[str, np.ndarray]]) -> None:
+        """ColBERT 多向量太占地方, 暂存为 .npy 文件, 路径记到 chunk_sparse 旁表."""
+        if not items:
+            return
+        from app.core.paths import data_dir
+
+        colbert_dir = data_dir() / "colbert"
+        colbert_dir.mkdir(parents=True, exist_ok=True)
+        with self._lock, db.transaction():
+            for cid, vec in items:
+                path = colbert_dir / f"{cid}.npy"
+                np.save(path, vec)
+                db.get_conn().execute(
+                    "INSERT OR REPLACE INTO chunk_sparse (chunk_id, weights_json) VALUES (?, ?)",
+                    (cid, json.dumps({"colbert_path": str(path.relative_to(data_dir()))})),
+                )
+
+    def get_sparse(self, chunk_id: str) -> dict[int, float] | None:
+        row = db.get_conn().execute(
+            "SELECT weights_json FROM chunk_sparse WHERE chunk_id = ? AND weights_json NOT LIKE '%colbert_path%'",
+            (chunk_id,),
+        ).fetchone()
+        if not row:
+            return None
+        try:
+            d = json.loads(row["weights_json"])
+            return {int(k): float(v) for k, v in d.items()}
+        except (json.JSONDecodeError, ValueError):
+            return None
+
+    def get_colbert_path(self, chunk_id: str) -> str | None:
+        row = db.get_conn().execute(
+            "SELECT weights_json FROM chunk_sparse WHERE chunk_id = ? AND weights_json LIKE '%colbert_path%'",
+            (chunk_id,),
+        ).fetchone()
+        if not row:
+            return None
+        try:
+            d = json.loads(row["weights_json"])
+            return d.get("colbert_path")
+        except json.JSONDecodeError:
+            return None
+
+    def score_sparse(
+        self, query_weights: dict[int, float], candidate_ids: list[str]
+    ) -> dict[str, float]:
+        """对 candidate 计算 sparse 分数 (q·d 内积). 0 表示完全无重叠."""
+        out: dict[str, float] = {}
+        if not query_weights:
+            return out
+        for cid in candidate_ids:
+            doc_w = self.get_sparse(cid)
+            if not doc_w:
+                out[cid] = 0.0
+                continue
+            # 公共 token 上的内积
+            s = 0.0
+            for tid, qw in query_weights.items():
+                dw = doc_w.get(tid)
+                if dw is not None:
+                    s += qw * dw
+            out[cid] = s
+        return out
+
+    def delete_by_doc(self, doc_id: str) -> int:
+        # 通过 doc chunks 关联删除
+        rows = db.get_conn().execute(
+            "SELECT id FROM chunks WHERE doc_id = ?", (doc_id,)
+        ).fetchall()
+        if not rows:
+            return 0
+        ids = [r["id"] for r in rows]
+        cur = db.get_conn().execute(
+            f"DELETE FROM chunk_sparse WHERE chunk_id IN ({','.join('?' * len(ids))})",
+            ids,
+        )
+        return cur.rowcount
+
+
+# ========== ChromaDB 客户端 ==========
+_chroma_client = None
+_chroma_collection = None
+_sparse_sidecar: SparseSidecar | None = None
+
+
+def get_chroma():
+    global _chroma_client, _chroma_collection, _sparse_sidecar
+    if _chroma_client is None:
+        import chromadb
+        from chromadb.config import Settings as ChromaSettings
+
+        chroma_dir()
+        _chroma_client = chromadb.PersistentClient(
+            path=str(settings.chroma_dir),
+            settings=ChromaSettings(anonymized_telemetry=False, allow_reset=False),
+        )
+        # ChromaDB v1.0+ 支持 multi-vector; 不指定 embedding_function (我们自己 embed)
+        _chroma_collection = _chroma_client.get_or_create_collection(
+            name=settings.chroma_collection,
+            metadata={"hnsw:space": "cosine"},
+            embedding_function=None,
+        )
+        # 旁路 sparse 索引
+        _sparse_sidecar = SparseSidecar(settings.sqlite_db_path)
+        logger.info(
+            "ChromaDB ready: dir=%s collection=%s",
+            settings.chroma_dir, settings.chroma_collection,
+        )
+    return _chroma_client, _chroma_collection, _sparse_sidecar
+
+
+# ========== Upsert ==========
+def upsert_chunks(
+    *,
+    ids: list[str],
+    embeddings: np.ndarray,             # (N, 1024) dense
+    documents: list[str],               # 文本
+    metadatas: list[dict[str, Any]],
+    sparse_weights: list[dict[int, float]] | None = None,
+    colbert_vecs: list[np.ndarray] | None = None,
+) -> None:
+    """写入 ChromaDB + 旁路 sparse/colbert."""
+    if not ids:
+        return
+    _, coll, sidecar = get_chroma()
+    coll.upsert(
+        ids=ids,
+        embeddings=embeddings.tolist(),
+        documents=documents,
+        metadatas=metadatas,
+    )
+    if sparse_weights:
+        sidecar.upsert_bulk(list(zip(ids, sparse_weights)))
+    if colbert_vecs and settings.enable_colbert:
+        sidecar.upsert_colbert(list(zip(ids, colbert_vecs)))
+
+
+# ========== Query ==========
+def query_dense(
+    query_emb: np.ndarray, k: int = 20, where: dict | None = None
+) -> list[tuple[str, float, dict]]:
+    _, coll, _ = get_chroma()
+    res = coll.query(
+        query_embeddings=[query_emb.tolist()],
+        n_results=k,
+        where=where,
+        include=["metadatas", "distances", "documents"],
+    )
+    if not res["ids"]:
+        return []
+    out: list[tuple[str, float, dict]] = []
+    for i, cid in enumerate(res["ids"][0]):
+        # cosine distance -> 转为 similarity
+        dist = res["distances"][0][i] if res["distances"] else 0.0
+        sim = 1.0 - dist
+        out.append((cid, sim, {
+            "text": res["documents"][0][i] if res["documents"] else "",
+            "meta": res["metadatas"][0][i] if res["metadatas"] else {},
+        }))
+    return out
+
+
+def rrf_fuse(
+    *ranked_lists: list[tuple[str, float, dict]],
+    k: int = 60,
+) -> list[tuple[str, float, dict]]:
+    """Reciprocal Rank Fusion.
+
+    每个 list 是 [(id, score, payload), ...], 排名越靠前 (index 0) 权重越高.
+    score = sum 1/(k + rank_i)
+    """
+    scores: dict[str, float] = {}
+    payloads: dict[str, dict] = {}
+    for ranked in ranked_lists:
+        for rank, (cid, _score, payload) in enumerate(ranked):
+            scores[cid] = scores.get(cid, 0.0) + 1.0 / (k + rank + 1)
+            if cid not in payloads:
+                payloads[cid] = payload
+            elif payload and payload.get("text"):
+                payloads[cid] = payload
+    out = sorted(scores.items(), key=lambda x: -x[1])
+    return [(cid, sc, payloads[cid]) for cid, sc in out]
+
+
+def hybrid_query(
+    *,
+    query_emb: np.ndarray,
+    query_sparse: dict[int, float] | None = None,
+    query_colbert_emb: np.ndarray | None = None,
+    k: int = 20,
+    where: dict | None = None,
+    over_retrieve: int = 50,
+) -> list[RetrievalHit]:
+    """三路混合检索 + RRF.
+
+    Args:
+        query_emb: dense 向量 (1024d)
+        query_sparse: 稀疏权重
+        query_colbert_emb: (T, 1024) 多向量
+        k: 最终返回 top-k
+        over_retrieve: 每路多取一些再融合
+    """
+    started = time.time()
+
+    # 路 1: dense (ChromaDB HNSW)
+    dense = query_dense(query_emb, k=over_retrieve, where=where)
+
+    # 路 2: sparse (旁路 + 反查)
+    sparse: list[tuple[str, float, dict]] = []
+    if query_sparse:
+        _, _, sidecar = get_chroma()
+        cand_ids = [cid for cid, _, _ in dense]  # dense top-N 作为候选, 避免全表
+        sparse_scores = sidecar.score_sparse(query_sparse, cand_ids)
+        # 按 sparse score 排序
+        sparse = sorted(
+            [
+                (cid, sparse_scores.get(cid, 0.0), {"text": "", "meta": {}})
+                for cid in cand_ids
+            ],
+            key=lambda x: -x[1],
+        )
+
+    # 路 3: colbert (late interaction)
+    colbert_ranked: list[tuple[str, float, dict]] = []
+    if settings.enable_colbert and query_colbert_emb is not None and len(query_colbert_emb) > 0:
+        from app.core.paths import data_dir
+        # 只对 dense top-N 计算 colbert
+        _, _, sidecar = get_chroma()
+        cand_ids = [cid for cid, _, _ in dense[:30]]
+        scored: list[tuple[str, float]] = []
+        for cid in cand_ids:
+            rel_path = sidecar.get_colbert_path(cid)
+            if not rel_path:
+                continue
+            full = data_dir() / rel_path
+            if not full.exists():
+                continue
+            try:
+                doc_vec = np.load(full)
+            except Exception:  # noqa: BLE001
+                continue
+            # max-sim
+            sims = doc_vec @ query_colbert_emb.T  # (T_doc, T_q)
+            if sims.size == 0:
+                continue
+            max_per_doc = sims.max(axis=0).mean()  # mean of per-query-token max
+            scored.append((cid, float(max_per_doc)))
+        colbert_ranked = sorted(scored, key=lambda x: -x[1])
+        colbert_ranked = [(cid, s, {"text": "", "meta": {}}) for cid, s in colbert_ranked]
+
+    # RRF 融合
+    fused = rrf_fuse(dense, sparse, colbert_ranked, k=60)[:k]
+
+    # 构造 RetrievalHit
+    hits: list[RetrievalHit] = []
+    for cid, rrf_score, payload in fused:
+        meta = payload.get("meta", {})
+        hits.append(RetrievalHit(
+            chunk_id=cid,
+            doc_id=meta.get("doc_id", ""),
+            text=payload.get("text", ""),
+            score=rrf_score,
+            page_no=meta.get("page_no"),
+            heading=meta.get("heading"),
+            context_prefix=meta.get("context_prefix"),
+            meta=meta,
+        ))
+
+    logger.debug("hybrid_query returned %d hits in %dms", len(hits), int((time.time() - started) * 1000))
+    return hits
+
+
+# ========== Delete ==========
+def delete_by_doc(doc_id: str) -> int:
+    """从 ChromaDB + sparse 旁路一并删除."""
+    _, coll, sidecar = get_chroma()
+    # 先列 id (ChromaDB v1.0 用 where 过滤删除)
+    try:
+        coll.delete(where={"doc_id": doc_id})
+    except Exception as e:  # noqa: BLE001
+        logger.warning("ChromaDB delete by where failed (%s), falling back to per-chunk", e)
+        # fallback: 列出来删
+        rows = db.get_conn().execute("SELECT id FROM chunks WHERE doc_id = ?", (doc_id,)).fetchall()
+        ids = [r["id"] for r in rows]
+        if ids:
+            coll.delete(ids=ids)
+    n = sidecar.delete_by_doc(doc_id)
+    return n

app/streaming/events.py

@@ -0,0 +1,84 @@
+"""AG-UI 兼容事件类型常量 + helper.
+
+AG-UI 协议: https://docs.ag-ui.com (CopilotKit 提出, 2025 起逐步成为 agent UI 事件标准)
+
+我们的 9 类事件:
+- thinking: Agent 推理过程 / 决策说明
+- agent_step: 节点生命周期 (running / done / error)
+- retrieval: 命中文档 ID + 分数
+- tool_call: 工具调用详情
+- token: LLM delta
+- citation: 引用片段
+- progress: 整体进度 0-100
+- done: 结束
+- error: 错误
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+# 事件类型常量 (防止拼写错)
+EV_THINKING = "thinking"
+EV_AGENT_STEP = "agent_step"
+EV_RETRIEVAL = "retrieval"
+EV_TOOL_CALL = "tool_call"
+EV_TOKEN = "token"
+EV_CITATION = "citation"
+EV_PROGRESS = "progress"
+EV_DONE = "done"
+EV_ERROR = "error"
+
+ALL_EVENTS: tuple[str, ...] = (
+    EV_THINKING, EV_AGENT_STEP, EV_RETRIEVAL, EV_TOOL_CALL,
+    EV_TOKEN, EV_CITATION, EV_PROGRESS, EV_DONE, EV_ERROR,
+)
+
+
+def sse_format(event: str, data: dict[str, Any]) -> str:
+    """格式化为标准 SSE 双行: `event: <type>\\ndata: <json>\\n\\n`."""
+    payload = json.dumps(data, ensure_ascii=False, default=str)
+    return f"event: {event}\ndata: {payload}\n\n"
+
+
+def sse_heartbeat() -> str:
+    """保活注释, 避免代理超时. 不属于事件, 不会触发前端 listener."""
+    return ": keepalive\n\n"
+
+
+def sse_done(usage: dict[str, int] | None = None, total_ms: int = 0) -> str:
+    return sse_format(EV_DONE, {"usage": usage or {}, "total_ms": total_ms})
+
+
+def sse_error(
+    code: str,
+    message: str,
+    *,
+    retryable: bool = False,
+    detail: dict[str, Any] | None = None,
+) -> str:
+    return sse_format(
+        EV_ERROR,
+        {"code": code, "message": message, "retryable": retryable, "detail": detail or {}},
+    )
+
+
+# 节点名常量 (在 LangGraph 里用到, 统一在此声明)
+NODE_ROUTE = "route"
+NODE_QUERY_REWRITE = "query_rewrite"
+NODE_RETRIEVE = "retrieve"
+NODE_RERANK = "rerank"
+NODE_TOOL = "tool_executor"
+NODE_ANSWER = "answer"
+NODE_EVALUATE = "evaluate"
+
+ALL_NODES: tuple[str, ...] = (
+    NODE_ROUTE, NODE_QUERY_REWRITE, NODE_RETRIEVE, NODE_RERANK,
+    NODE_TOOL, NODE_ANSWER, NODE_EVALUATE,
+)
+
+
+NodeName = Literal[
+    "route", "query_rewrite", "retrieve", "rerank",
+    "tool_executor", "answer", "evaluate",
+]

app/streaming/sse.py

@@ -0,0 +1,38 @@
+"""SSE generator 辅助. 提供 ping / retry / error 处理."""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import AsyncIterator
+
+from app.streaming.events import sse_format, sse_heartbeat
+
+logger = logging.getLogger(__name__)
+
+
+async def heartbeat_pinger(interval: float = 15.0) -> AsyncIterator[str]:
+    """无限流式发送 SSE 注释保活. 配合 `asyncio.Queue` 一起使用."""
+    try:
+        while True:
+            await asyncio.sleep(interval)
+            yield sse_heartbeat()
+    except asyncio.CancelledError:
+        return
+
+
+async def event_stream(
+    queue: asyncio.Queue[tuple[str, dict] | None],
+) -> AsyncIterator[str]:
+    """从 asyncio.Queue 读取事件并序列化为 SSE. 收到 None 表示结束."""
+    while True:
+        item = await queue.get()
+        if item is None:
+            break
+        event, data = item
+        yield sse_format(event, data)
+
+
+def safe_json(data: dict) -> str:
+    """防御性 JSON 序列化."""
+    return json.dumps(data, ensure_ascii=False, default=str)

pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-chatbot-backend"
+version = "0.1.0"
+description = "Agentic multimodal RAG customer service backend"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "You" }]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["app*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+ignore_missing_imports = true

requirements.txt

@@ -0,0 +1,54 @@
+# ========== Web 框架 ==========
+fastapi>=0.115,<1.0
+uvicorn[standard]>=0.32,<1.0
+python-multipart>=0.0.12          # 文件上传
+sse-starlette>=2.1.3              # SSE 增强
+
+# ========== 配置 ==========
+pydantic>=2.9,<3.0
+pydantic-settings>=2.5,<3.0
+python-dotenv>=1.0
+
+# ========== LLM 抽象 (OpenAI 兼容) ==========
+openai>=1.60,<2.0                 # MiniMax-M3 / OpenAI / 兼容 provider 共用
+httpx>=0.27                       # AsyncOpenAI 依赖
+
+# ========== Agent / LangGraph ==========
+langgraph>=0.3,<1.0
+langchain-core>=0.3,<1.0
+langgraph-checkpoint-sqlite>=2.0  # 实施前核对最新稳定版
+pydantic-ai>=0.2,<1.0
+
+# ========== 文档解析 ==========
+docling>=2.30,<2.74               # 主力：结构感知 + 跨页表 + OCR
+# marker-pdf>=1.10                  # 兜底：文字密集型 PDF (Intel Mac 暂不支持)
+# mineru>=0.22                    # 可选：学术论文 / 复杂双栏 (按需安装)
+
+# ========== Embedding / Reranker ==========
+FlagEmbedding>=1.2                # BGE-M3 + bge-reranker-v2-m3
+sentence-transformers>=3.0        # 备选 embedding 库
+torch>=2.2                        # FlagEmbedding 依赖
+
+# ========== 向量库 ==========
+chromadb>=0.5,<2.0                # 1.0+ Rust core
+rank-bm25>=0.2.2                  # BM25 备用 (当前用 BGE-M3 稀疏通路, 留作降级)
+
+# ========== 持久化 ==========
+huggingface_hub>=0.30             # snapshot_download / upload_folder
+
+# ========== 分块 / NLP ==========
+tiktoken>=0.7                     # token 计数
+nltk>=3.9                         # 句子切分
+tenacity>=9.0                     # 重试
+cachetools                        # LLM 缓存
+
+# ========== 评估 / 可观测性 ==========
+# ragas>=0.2                        # RAG 质量离线评估
+# deepeval>=1.0                     # 质量门禁
+
+# ========== 测试 ==========
+pytest>=8.0
+pytest-asyncio>=0.23
+pytest-cov>=5.0
+httpx>=0.27                       # TestClient
+respx>=0.21                       # mock httpx