项目地图:从浏览器到 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 和测试分层怎样保证这套代码可复现。