从零搭建第一个AI应用:FastAPI+LLM API调用完整教程

作者:技术拾光时间:2026-06-03 13:53:13浏览:473

从零搭建完整的AI对话应用,涵盖FastAPI后端、LLMAPI封装、流式输出与SSE实现、上下文截断管理、前端打字机效果渲染及Docker部署。统一调用层便于切换模型,内存会话与截断策略控制上下文长度,适合快速上手AI应用全流程开发。

前言

市面上讲 AI 应用开发的教程不少,但多数都在教怎么调 API,真正带你搭一个完整应用的却不多见。这篇文章的目标很明确:从零开始,手把手搭建一个完整的 AI 对话应用。后端、前端、API 封装、流式输出、生产部署,全流程走一遍。

从零搭建第一个AI应用:FastAPI+LLM API调用完整教程

最终效果是一个可以对话的 AI 聊天应用,支持流式打字输出,浏览器打开就能直接用。

Step 1:项目初始化

目录结构

ai-chat-app/ ├── main.py # FastAPI 入口 ├── llm.py # LLM API 封装 ├── requirements.txt ├── .env # 配置文件(不提交 Git) ├── static/ │ └── index.html # 前端页面 └── .gitignore

安装依赖

mkdir ai-chat-app && cd ai-chat-app python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate

# requirements.txt fastapi==0.115.0 uvicorn[standard]==0.30.0 python-dotenv==1.0.0 openai==1.50.0 jinja2==3.1.4 python-multipart==0.0.12

pip install -r requirements.txt

环境变量

# .env LLM_API_KEY=sk-your-api-key-here LLM_BASE_URL=https://api.deepseek.com/v1 LLM_MODEL=deepseek-chat SITE_NAME=AI Chat

Step 2:封装 LLM API

关键在于设计一个统一的 LLM 调用层。直接在业务代码里写 API 调用,后续换模型会非常痛苦。而把所有调用逻辑收敛到 llm.py 这一个文件里,以后想切换模型,改这一个地方就够了。

# llm.py import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client = OpenAI( api_key=os.getenv("LLM_API_KEY"), base_url=os.getenv("LLM_BASE_URL"), ) MODEL = os.getenv("LLM_MODEL", "deepseek-chat") def chat_sync(messages, temperature=0.7, max_tokens=2048): """同步调用 LLM,返回完整响应。""" response = client.chat.completions.create( model=MODEL, messages=messages, temperature=temperature, max_tokens=max_tokens, ) return response.choices[0].message.content def chat_stream(messages, temperature=0.7, max_tokens=2048): """流式调用 LLM,返回迭代器。""" response = client.chat.completions.create( model=MODEL, messages=messages, temperature=temperature, max_tokens=max_tokens, stream=True, ) for chunk in response: delta = chunk.choices[0].delta if chunk.choices else None if delta and delta.content: yield delta.content def count_tokens(text): """估算 token 数(粗略,中英文混合按 1.5 字符/token)""" return int(len(text) / 1.5)

为什么这样设计?chat_sync 负责批量处理、后台任务等不需要实时的场景;chat_stream 则专门应对对话场景,打字机效果能极大提升用户体验;count_tokens 用来控制上下文长度,防止超出模型限制,这是一个很容易被忽视但相当重要的环节。

Step 3:搭建 FastAPI 后端

# main.py import os import time from fastapi import FastAPI, Request from fastapi.responses import HTMLResponse, StreamingResponse, JSONResponse from fastapi.staticfiles import StaticFiles from dotenv import load_dotenv from llm import chat_sync, chat_stream, count_tokens load_dotenv() app = FastAPI(title=os.getenv("SITE_NAME", "AI Chat")) # 挂载静态文件 app.mount("/static", StaticFiles(directory="static"), name="static") # 会话历史存储(生产环境应该用 Redis) sessions = {} MAX_HISTORY_TOKENS = 4000 # 上下文窗口上限 def get_session(session_id: str) -> list: """获取或创建会话。""" if session_id not in sessions: sessions[session_id] = [] return sessions[session_id] def trim_history(messages: list, max_tokens: int = MAX_HISTORY_TOKENS): """截断对话历史,保留最近的对话。""" total = 0 trimmed = [] for msg in reversed(messages): tokens = count_tokens(msg["content"]) if total + tokens > max_tokens: break total += tokens trimmed.append(msg) trimmed.reverse() # 如果截断后第一条不是 system,补一个 if trimmed and trimmed[0]["role"] != "system": trimmed.insert(0, {"role": "system", "content": "你是一个有用的 AI 助手。"}) return trimmed @app.get("/", response_class=HTMLResponse) async def index(): with open("static/index.html", "r", encoding="utf-8") as f: return f.read() @app.post("/api/chat") async def chat(request: Request): """对话接口(非流式)。""" body = await request.json() session_id = body.get("session_id", "default") user_message = body.get("message", "") if not user_message.strip(): return JSONResponse({"error": "消息不能为空"}, status_code=400) history = get_session(session_id) history.append({"role": "user", "content": user_message}) # 截断上下文 messages = trim_history(history) # 调用 LLM reply = chat_sync(messages) history.append({"role": "assistant", "content": reply}) return JSONResponse({"reply": reply}) @app.post("/api/chat/stream") async def chat_stream_endpoint(request: Request): """对话接口(流式)。""" body = await request.json() session_id = body.get("session_id", "default") user_message = body.get("message", "") if not user_message.strip(): return JSONResponse({"error": "消息不能为空"}, status_code=400) history = get_session(session_id) history.append({"role": "user", "content": user_message}) messages = trim_history(history) async def generate(): full_reply = "" for chunk in chat_stream(messages): full_reply += chunk yield f"data: {chunk}" # 保存完整回复到历史 history.append({"role": "assistant", "content": full_reply}) yield f"data: [DONE]" return StreamingResponse( generate(), media_type="text/event-stream", headers={ "Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no", # 禁用 Nginx 缓冲 }, ) @app.post("/api/clear") async def clear_session(request: Request): """清空对话历史。""" body = await request.json() session_id = body.get("session_id", "default") sessions[session_id] = [] return JSONResponse({"status": "ok"}) # 启动 if __name__ == "__main__": import uvicorn uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

关键设计说明

上下文管理(trim_history):这是 AI 应用最容易忽略的问题。模型有上下文长度限制(8K/32K/128K tokens 不等),对话不断累积早晚会超限。策略是:按 token 数从后往前截断,保留最近的对话;确保 system prompt 始终在(被截掉了就补一个默认的);留出余量,不等到真正超限才截断。

流式响应(Server-Sent Events):选择 SSE 而不是 WebSocket,原因很明确——SSE 是单向的(服务端→客户端),正好符合"流式输出"的场景。SSE 基于 HTTP,兼容性好,不会被防火墙拦截。WebSocket 是双向的,更适合需要客户端推送的场景(如实时协作)。

会话管理:这里用内存字典存储会话,生产环境应该换成 Redis。Redis 天然支持过期时间(TTL),可以自动清理长时间不活跃的会话;多进程或多实例时也能共享会话状态。

Step 4:前端界面

AI Chat

AI Chat

前端要点

流式渲染用 fetch + ReadableStream 读取 SSE,每收到一个 chunk 就追加到页面,自然形成打字机效果。回复中用 typing-cursor CSS 类显示闪烁的光标,回复完成后移除。每次内容更新都自动滚动到底部,确保用户体验流畅。

Step 5:运行与部署

本地运行

python main.py

浏览器打开 http://localhost:8000,就能看到对话界面了。

Docker 部署

# Dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

docker build -t ai-chat-app . docker run -d -p 8000:8000 --env-file .env ai-chat-app

Nginx 反向袋里

server { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_read_timeout 300s; # SSE 需要禁用缓冲 proxy_buffering off; chunked_transfer_encoding on; } }

常见问题

Q:流式输出不流畅怎么办?

排查步骤:首先确认 X-Accel-Buffering: no 头已设置(Nginx 默认会缓冲 SSE);接着确认 proxy_buffering off 已正确配置;最后检查 LLM API 本身的响应速度——有些模型首 Token 延迟确实很高。

Q:API Key 安全吗?

.env 文件不要提交到 Git,用 .gitignore 忽略它。生产环境建议使用环境变量或密钥管理服务(如 AWS Secrets Manager、Vault)。

Q:如何支持多模型?

在 llm.py 中扩展即可:

MODELS = { "deepseek": OpenAI(api_key=..., base_url=...), "openai": OpenAI(api_key=...), "claude": Anthropic(api_key=...), }

前端传入 model 参数,后端根据参数选择对应的客户端。

总结

完成的内容可以汇总如下:

组件说明
LLM API 封装层同步 + 流式接口,方便切换模型
后端 API对话、流式响应、上下文管理、会话控制
前端界面流式渲染、打字机效果、对话体验
部署方案Docker + Nginx 反向袋里

这个应用虽然基础,但已经涵盖了 AI 应用的核心架构。下一篇,我们会在此基础上深入 Prompt 工程——如何设计可靠的结构化 Prompt,让模型的输出更可控,更符合预期。