跳到主要内容
Ed. notes

项目地图:从浏览器到 FastAPI

长文 · 2026-11-11 · 合集第 2 / 11 篇

  • 后端
  • FastAPI
  • RAG
第 2 / 11 篇 · 查看全部章节 → 当前:项目地图:从浏览器到 FastAPI

结论

读这个后端,从两个 HTTP 入口往下追:/api/search 追到 repository.py,/api/chat 追到 graph.py。两条线交汇在同一个检索函数上,agent/ 则是不依赖 HTTP 的纯逻辑层。如果从前端进入,再往前加一段:浏览器先请求 Nuxt 的同源代理,由代理转发到 FastAPI。

问题与设计

仓库有三个顶层目录:

frontend/   Nuxt 4 + Nitro,npm 项目
backend/    FastAPI + 入库 + 检索 + 流式问答,uv 项目
content/    唯一写作源,两边直接读,不复制

content/ 共享的是 Markdown 文件,不是运行时代码。前端用 TypeScript 解析,后端用 Python 重新解析;两边必须遵守同一套 slug、草稿和目录规则。

浏览器侧的完整路径:

/chat 页面
  → useChat() POST /api/assistant/chat
  → Nuxt server route: frontend/server/api/assistant/chat.post.ts
  → FastAPI POST /api/chat
  → retrieve → generate/refuse
  → SSE: sources / token / done / error
  → ReadableStream 回到浏览器

Nuxt 代理不是访问控制。它解决同源、隐藏后端地址和流式转发,生产模式下仍然直接返回 404;真正的鉴权、配额和限流还没做。

backend/src/backend/ 的分层很薄:

app.py          路由、依赖组装、SSE
config.py       配置、启动校验、错误契约
db.py           建表与连接
ingest.py       入库命令
repository.py   检索 SQL
agent/          内容、切片、embedding、模型、图

agent/ 不导入 FastAPI,也不处理请求对象。依赖方向是 app.py → agent/,反过来不成立。这条边界让内容加载、切片和 RAG 图可以脱离 Web 层单独测试。

关键代码

代理只做三件事:开关检查、请求体转发、把上游流原样变成 Nitro 的 ReadableStream。

if (!options.enabled || options.production) {
  throw createError({ statusCode: 404, statusMessage: 'Not Found' })
}

const endpoint = new URL('/api/chat', backendBaseUrl)
const upstream = await fetch(endpoint, {
  method: 'POST',
  headers: { 'content-type': contentType, accept: 'text/event-stream' },
  body: new Uint8Array(body),
  signal: upstreamController.signal,
})

/api/search 的链路:

SearchRequest → embed_query → connect → register_vector → search_chunks → results

路由本身很短:

@app.post("/api/search")
def search(
    payload: SearchRequest,
    settings: Settings = Depends(get_settings),
    provider: EmbeddingProvider = Depends(get_embedding_provider),
):
    vector = Vector(provider.embed_query(payload.query))
    with connect(settings.database_url) as conn:
        register_vector(conn)
        results = search_chunks(conn, vector, payload.limit)
    return {"query": payload.query, "results": [hit.as_result() for hit in results]}

/api/chat 复用同一个 search_chunks(),只是把它包成 retriever:

def get_retriever(...) -> Retriever:
    def retrieve(query: str, top_k: int) -> list[ChunkHit]:
        vector = Vector(provider.embed_query(query))
        with connect(settings.database_url) as conn:
            register_vector(conn)
            return search_chunks(conn, vector, top_k)
    return retrieve

图只有三个节点:

START → retrieve → generate → END
                 ↘ refuse   → END

retrieve 找切片,generate 拼提示词并流式调用模型;没有切片时走 refuse,不调用模型。

验证

确认 src layout 生效:

uv run python -c "import backend; print(backend.__file__)"
backend/src/backend/__init__.py

确认数据库是独立基础设施:

docker compose -f infra/docker-compose.dev.yml ps
infra-postgres-1   pgvector/pgvector:pg16   Up (healthy)

边界

  • app.py 同时承担路由、错误映射和依赖组装,当前规模够用;加鉴权、配额、会话后需要拆。
  • 每次请求新建数据库连接,没有连接池;内容量小不是瓶颈,并发上来要换。
  • /api/chat 会产生真实模型费用,当前没有鉴权、配额和限流,不能公开暴露。

下一篇看工程骨架:pyproject.toml、src layout 和测试分层怎样保证这套代码可复现。