大模型应用开发 / 系统课时

创建 FastAPI 项目

创建 FastAPI 项目

这次要把知识库问答接口组织成可运行的 FastAPI 工程。完成后,服务具备健康检查、请求参数校验和明确的未实现响应;后续接入检索、重排与答案生成时,只需扩展服务层,不必把业务逻辑堆进应用入口。

学习目标

  • 建立清晰的配置、接口、数据模型和服务分层。
  • 编写可启动的 FastAPI 入口及问答路由骨架。
  • 用实际 HTTP 请求验证成功响应和未接入功能的错误响应。

规划目录与模块边界

项目根目录命名为 rag-service,将代码放在 app 包内。各文件只承担一类职责,避免后续接入向量数据库时修改全部接口代码。

  • app/main.py:创建应用、注册路由、提供进程健康检查。
  • app/config.py:读取环境变量,不存储密码或密钥常量。
  • app/schemas.py:使用 Pydantic 定义并校验请求结构。
  • app/api/ask.py:接收 HTTP 请求、映射业务异常和返回结果。
  • app/services/qa_service.py:承接未来的检索与问答编排。
  • app/infrastructure/:预留向量库和大模型客户端,本课不接入。

问答请求从路由进入服务层,依赖的外部组件以后再接上。下图中虚线区域表示尚未实现的基础设施;健康检查只表明 API 进程可响应,不代表向量库或模型已经就绪。

FastAPI 知识库服务分层与请求流向

初始化工程并安装依赖

下面命令适用于 macOS 或 Linux 的 Bash,要求已安装 Python 3.10 或更新版本。先创建包目录和依赖清单,再使用虚拟环境安装;__init__.py 使导入路径更直观。

bash
# 创建项目与 Python 包
mkdir -p rag-service/app/api rag-service/app/services rag-service/app/infrastructure
cd rag-service
touch app/__init__.py app/api/__init__.py app/services/__init__.py
printf 'fastapi\nuvicorn[standard]\n' > requirements.txt

# 安装并检验依赖
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -q -r requirements.txt
python -c 'import fastapi, uvicorn; print("dependencies ok")'

预期输出(安装过程可能另有提示):

text
dependencies ok

Windows PowerShell 可将创建目录和文件的步骤改为手动操作,并使用 py -m venv .venv 与 .venv\Scripts\Activate.ps1 激活环境。正式部署时应固定并审计依赖版本,避免不同机器安装到不一致的版本。

编写配置和请求模型

新建 app/config.py,统一读取部署时提供的环境变量。VECTOR_DB_URL 暂时允许为空,不要在未接入向量库时填一个看似有效却无法连接的地址。

python
import os

# 启动时读取配置;向量库连接在后续课时再使用
APP_NAME = os.getenv("APP_NAME", "RAG Knowledge Service")
VECTOR_DB_URL = os.getenv("VECTOR_DB_URL")

新建 app/schemas.py,请求模型限制问题长度为 1~2000 个字符。FastAPI 会在进入业务函数前进行验证;空字符串会得到 HTTP 422,而不是传到服务层。

python
from pydantic import BaseModel, Field


class AskRequest(BaseModel):
    # 在接口边界限制输入规模,避免无限长的请求直达模型
    question: str = Field(min_length=1, max_length=2000)

连接问答服务、路由与入口

新建 app/services/qa_service.py。此时还没有索引、召回器或 LLM,不应返回伪造的知识库答案;用明确异常标记待实现功能,等接入真实问答链时再替换函数体。

python
def answer_question(question: str) -> str:
    # 保留业务入口,但不把未实现的检索伪装成成功
    raise NotImplementedError("RAG pipeline is not configured")

新建 app/api/ask.py,路由只负责参数验证与异常到 HTTP 状态码的映射。未接入的问答能力返回 501,方便客户端和自动化测试区分正常回答与尚未实现。

python
from fastapi import APIRouter, HTTPException
from app.schemas import AskRequest
from app.services.qa_service import answer_question

router = APIRouter(prefix="/api", tags=["qa"])


@router.post("/ask")
def ask(request: AskRequest) -> dict[str, str]:
    try:
        return {"answer": answer_question(request.question)}
    except NotImplementedError as exc:
        # 501表示该端点的问答能力尚未实现
        raise HTTPException(status_code=501, detail=str(exc)) from exc

最后新建 app/main.py。主文件只负责装配路由和基础探活,不包含检索代码,也不应在健康检查中假装校验了外部依赖。

python
from fastapi import FastAPI
from app.api.ask import router as ask_router
from app.config import APP_NAME

app = FastAPI(title=APP_NAME)
app.include_router(ask_router)


@app.get("/health")
def health_check() -> dict[str, str]:
    # 只检查HTTP服务是否正常响应
    return {"status": "ok"}

以上五个 Python 文件都应放在对应路径下。app/infrastructure/ 目前可保持为空;启动后 /docs 会展示自动生成的交互式接口文档,其中包含 /health 和 /api/ask。

启动服务并验证响应

在项目根目录、已激活虚拟环境的终端执行启动命令;开发时绑定回环地址即可,不必将未加鉴权的接口暴露到公网。

bash
# 在 rag-service 目录内执行
uvicorn app.main:app --host 127.0.0.1 --port 8000

预期输出中的关键一行如下,其他日志及动态值可能随运行环境变化:

text
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

保持服务运行,另开终端执行两次请求。第一条检查进程健康,第二条验证问答路由已经注册,但 RAG 业务尚未接通。

bash
# 先验证健康检查,再验证未实现的问答接口
curl -sS -w '\nHTTP %{http_code}\n' http://127.0.0.1:8000/health
curl -sS -w '\nHTTP %{http_code}\n' -X POST \
  -H 'Content-Type: application/json' \
  -d '{"question":"如何申请知识库权限?"}' \
  http://127.0.0.1:8000/api/ask

预期输出(依次为响应体和 HTTP 状态码):

text
{"status":"ok"}
HTTP 200
{"detail":"RAG pipeline is not configured"}
HTTP 501

若提示 ModuleNotFoundError: No module named 'app',先确认工作目录为 rag-service,并用同一虚拟环境启动 Uvicorn。若端口被占用,可把启动参数和两条请求中的 8000 同时更换为其他空闲端口。健康检查返回 200、问答接口返回 501,说明项目骨架已工作,下一步可以安全地接入真实的检索和生成流程。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建 FastAPI 项目

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通