从零搭建完整的AI对话应用,涵盖FastAPI后端、LLMAPI封装、流式输出与SSE实现、上下文截断管理、前端打字机效果渲染及Docker部署。统一调用层便于切换模型,内存会话与截断策略控制上下文长度,适合快速上手AI应用全流程开发。
从零搭建第一个AI应用:FastAPI+LLM API调用完整教程
时间:2026-06-03
浏览:472
文章目录
前言
市面上讲 AI 应用开发的教程不少,但多数都在教怎么调 API,真正带你搭一个完整应用的却不多见。这篇文章的目标很明确:从零开始,手把手搭建一个完整的 AI 对话应用。后端、前端、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:前端界面
流式渲染用 浏览器打开 排查步骤:首先确认 .env 文件不要提交到 Git,用 在 前端传入 完成的内容可以汇总如下: 这个应用虽然基础,但已经涵盖了 AI 应用的核心架构。下一篇,我们会在此基础上深入 Prompt 工程——如何设计可靠的结构化 Prompt,让模型的输出更可控,更符合预期。
前端要点
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 安全吗?
.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 反向袋里
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。