大模型API应用开发五层技术栈与选型指南
作者:da吃一鲸8862026.11.17 03:42浏览量:0简介:本文按模型接入、SSE流式输出、应用编排、RAG知识增强和工程运维五层拆解大模型应用的技术栈,给出可直接运行的Python后端与前端代码、依赖版本、安全清单和场景化选型表。读完可以搭出一个流式问答服务,并知道每层该用什么工具。
开发基于大语言模型(LLM)API的应用,技术栈不是某一个框架,而是五组配合使用的组件:模型接入、SSE流式输出、应用编排、RAG知识增强和工程运维。每层解决一类问题。先弄清每层的职责,再决定用哪些工具,比先选框架更稳妥。
本文代码基于 OpenAI 兼容接口编写。LLM_BASE_URL、LLM_API_KEY、LLM_MODEL 等配置需要替换为实际值。不同厂商的字段可能略有差异,接入前以官方文档为准。
环境与依赖
示例在 Python 3.10 及以上版本编写。以下版本号是示例中固定的版本,升级前请做回归测试。
pip install httpx==0.27.2 requests==2.32.3 fastapi==0.115.0 uvicorn==0.30.6 pydantic==2.9.2
密钥和地址通过环境变量注入,不写进代码:
export LLM_BASE_URL="https://your-llm-api-endpoint/v1"export LLM_API_KEY="your-api-key"export LLM_MODEL="your-model-name"export LLM_EMBED_MODEL="your-embedding-model-name"
项目按层拆分:llm_client.py 放第一节代码,app.py 放第二节后端,index.html 放前端。启动后端:
uvicorn app:app --reload
一、模型接入层:统一调用、鉴权与重试
模型接入层是应用与模型服务之间的边界,常见形态有四种:
- HTTP API 调用:用 POST 请求发送消息列表和参数,获取返回结果。
- SDK 调用:官方或社区 SDK 封装了鉴权、重试和流式解析,减少重复代码。
- 多模型统一接入:通过网关或平台层屏蔽不同模型的接口差异。
- 鉴权与配额管理:管理 API Key、访问权限、调用频率和费用额度。
业务代码不应直接散落模型请求。更稳妥的做法是抽出一个客户端,把超时、重试和模型选择集中在一处。以后切换模型、灰度发布或降级时,只改这一处。
下面是简化版客户端。它只对超时和临时性错误(429 限流、500 及以上的服务端错误)做指数退避重试。400 这类参数错误重试没有意义,直接抛出。
# llm_client.pyimport osimport timeimport httpxRETRYABLE_STATUS = {429, 500, 502, 503}def get_config() -> tuple[str, str, str]:base_url = os.getenv("LLM_BASE_URL", "").rstrip("/")api_key = os.getenv("LLM_API_KEY", "")model = os.getenv("LLM_MODEL", "")if not (base_url and api_key and model):raise RuntimeError("请设置 LLM_BASE_URL、LLM_API_KEY、LLM_MODEL 环境变量")return base_url, api_key, modelclass LLMClient:def __init__(self, base_url: str, api_key: str, model: str,timeout: float = 30.0, max_retries: int = 2):self.base_url = base_url.rstrip("/")self.api_key = api_keyself.model = modelself.timeout = timeoutself.max_retries = max_retriesdef chat(self, messages: list[dict]) -> str:payload = {"model": self.model, "messages": messages, "stream": False}headers = {"Authorization": f"Bearer {self.api_key}"}for attempt in range(self.max_retries + 1):try:resp = httpx.post(f"{self.base_url}/chat/completions",json=payload,headers=headers,timeout=self.timeout,)except httpx.TimeoutException:if attempt == self.max_retries:raisetime.sleep(2 ** attempt)continueif resp.status_code in RETRYABLE_STATUS and attempt < self.max_retries:time.sleep(2 ** attempt)continueresp.raise_for_status()return resp.json()["choices"][0]["message"]["content"] or ""raise RuntimeError("重试次数已用完")
企业选型时,可以对比各家云厂商和开源网关的模型列表、价格、响应延迟和服务等级协议(SLA)。这些数字应以自己的业务数据实测为准,宣传口径只作参考。
二、流式通信层:为什么多数应用选择 SSE
大模型逐字生成内容。如果等全部生成完再返回,用户要等很久。流式传输让用户边生成边看到结果。SSE(Server-Sent Events)是实现这一效果最常用的协议之一。它基于 HTTP,服务端可以持续向客户端推送数据。
1. 通信方式对比
| 技术 | 通信方向 | 典型场景 | 主要限制 |
|---|---|---|---|
| 普通 HTTP | 客户端请求,服务端一次返回 | 结构化结果、短问答 | 无法逐字输出 |
| SSE | 服务端单向推送 | 流式生成、进度通知 | 只能服务端推给客户端 |
| WebSocket | 双向通信 | 实时协作、语音对话 | 需维护连接状态,部署更复杂 |
对于多数问答类应用,SSE 已经够用。它基于 HTTP,可以复用现有的网关、鉴权和负载均衡。用户中途停止生成,前端用 AbortController 中止请求即可,不必为此引入 WebSocket。
本文示例用 POST 传递问题,原生 EventSource 只支持 GET,所以前端改用 fetch 读取流。用 fetch 时,断线重连要由前端自己实现。
2. SSE 数据格式与换行
SSE 每条事件以 data: 开头。事件结尾必须是一个空行,也就是两个换行符。浏览器靠这个空行判断一条事件已经结束,缺少它,事件就不会被派发给前端。
data: {"delta": "你"}data: {"delta": "好"}data: [DONE]
上面是本文约定的简化格式,并非某个厂商的标准返回。OpenAI 兼容接口的真实流式返回中,增量文本位于 choices[0].delta.content。后端负责把真实结构转换成简化格式,前端只处理一种格式。上游厂商更换时,也只需修改后端。
3. 后端:读取上游流并转发 SSE
下面的生成器从上游逐段读取增量文本。它处理了三类常见问题:choices 是数组,必须取 choices[0];部分事件没有 choices,需要跳过;content 可能为 null,需要兜底。单个无法解析的事件只记日志并跳过,不会中断整条流。
# app.pyimport jsonimport loggingimport requestsfrom fastapi import FastAPIfrom fastapi.responses import StreamingResponsefrom pydantic import BaseModel, Fieldfrom llm_client import get_configlogger = logging.getLogger(__name__)app = FastAPI()class ChatRequest(BaseModel):message: str = Field(min_length=1, max_length=4000)def upstream_deltas(messages: list[dict]):base_url, api_key, model = get_config()headers = {"Authorization": f"Bearer {api_key}","Content-Type": "application/json",}payload = {"model": model, "messages": messages, "stream": True}with requests.post(f"{base_url}/chat/completions", headers=headers,json=payload, stream=True, timeout=(5, 60)) as resp:resp.raise_for_status()for raw_line in resp.iter_lines():if not raw_line:continueline = raw_line.decode("utf-8")if not line.startswith("data:"):continuedata = line[len("data:"):].strip()if data == "[DONE]":breaktry:chunk = json.loads(data)except json.JSONDecodeError:logger.warning("跳过无法解析的上游事件")continuechoices = chunk.get("choices") or []if not choices:continue # 统计、心跳类事件没有 choiceschoice = choices[0]delta = (choice.get("delta") or {}).get("content") or ""if delta:yield deltaif choice.get("finish_reason"):break@app.post("/api/chat")def chat(req: ChatRequest):messages = [{"role": "user", "content": req.message}]def event_stream():try:for delta in upstream_deltas(messages):payload = json.dumps({"delta": delta}, ensure_ascii=False)yield f"data: {payload}\n\n"yield "data: [DONE]\n\n"except Exception:logger.exception("上游调用失败")payload = json.dumps({"error": "upstream_error"})yield f"data: {payload}\n\n"yield "data: [DONE]\n\n"headers = {"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}return StreamingResponse(event_stream(),media_type="text/event-stream",headers=headers)
event_stream 是同步生成器,Starlette 会把它放到线程池中迭代,所以阻塞的 requests 调用不会卡住事件循环。并发量很高时,可以改用 httpx.AsyncClient 和异步生成器。
X-Accel-Buffering: no 告诉 Nginx 关闭响应缓冲。如果反向代理开启了缓冲,前端会等到整段内容结束才一次性收到。
4. 前端:用 fetch 读取 ReadableStream
<!-- index.html --><input id="question" placeholder="输入问题"><button id="send">发送</button><div id="output"></div><script>async function askStream(message, onDelta) {const resp = await fetch("/api/chat", {method: "POST",headers: { "Content-Type": "application/json" },body: JSON.stringify({ message }),});if (!resp.ok) throw new Error(`HTTP ${resp.status}`);const reader = resp.body.getReader();const decoder = new TextDecoder("utf-8");let buffer = "";while (true) {const { value, done } = await reader.read();if (done) break;buffer += decoder.decode(value, { stream: true });let sep;while ((sep = buffer.indexOf("\n\n")) !== -1) {const eventText = buffer.slice(0, sep);buffer = buffer.slice(sep + 2);for (const line of eventText.split("\n")) {if (!line.startsWith("data:")) continue;const data = line.slice(5).trim();if (data === "[DONE]") {await reader.cancel();return;}const obj = JSON.parse(data);if (obj.error) throw new Error(obj.error);if (obj.delta) onDelta(obj.delta);}}}}document.getElementById("send").addEventListener("click", () => {const output = document.getElementById("output");output.textContent = "";const question = document.getElementById("question").value;askStream(question, (text) => {output.textContent += text;}).catch((err) => {output.textContent += `\n[错误] ${err.message}`;});});</script>
buffer 用来拼接跨网络包的数据。一个事件可能被切成两段到达,也可能一次到达多个事件,所以要按空行切分,而不是逐个网络包解析。
如果前端和页面不在同一个域名下,后端需要配置 CORS,并把允许的来源写成明确列表。
三、应用编排层:历史、流程与降级
模型接入层解决“怎么调用”,编排层解决“按什么顺序调用、带什么上下文”。编排层通常负责四件事:拼装系统提示词和历史消息,裁剪过长的历史,按步骤组织检索和生成,以及在某一步失败时降级。
# orchestrator.pyfrom typing import Callable, Optionalfrom llm_client import LLMClientSYSTEM_PROMPT = "你是一名技术文档助手。回答要简洁,依据不足时明确说明。"class Conversation:def __init__(self, system_prompt: str = SYSTEM_PROMPT, max_turns: int = 10):self.system = {"role": "system", "content": system_prompt}self.history: list[dict] = []self.max_turns = max_turns # 必须大于 0def build_messages(self, user_text: str) -> list[dict]:recent = self.history[-self.max_turns * 2:]return [self.system, *recent, {"role": "user", "content": user_text}]def record(self, user_text: str, answer: str) -> None:self.history.append({"role": "user", "content": user_text})self.history.append({"role": "assistant", "content": answer})def answer(question: str, conv: Conversation, client: LLMClient,retrieve: Optional[Callable[[str], list[str]]] = None) -> str:if retrieve is None:prompt = questionelse:from rag import build_rag_prompt # 第四节定义prompt = build_rag_prompt(question, retrieve(question))reply = client.chat(conv.build_messages(prompt))conv.record(question, reply) # 历史只保存用户原问题,不保存检索片段return reply
历史裁剪按轮数截取。max_turns 控制上下文长度,也控制每次请求的费用。轮数够用即可,不必保留全部对话。
流程简单、步骤固定时,自己写几十行编排代码就够了,便于调试和测试。步骤多、有分支、需要人工审核或长时间等待时,再考虑图式编排框架,例如 LangGraph。
检索到的文档内容属于数据,不是指令。文档里可能混入“忽略之前的指令”之类的文字,这类提示注入要靠提示词约束和输出检查共同防范。
四、RAG 知识增强层:让模型依据自己的资料回答
RAG(检索增强生成)的流程是:切分文档、生成向量、检索相关片段、把片段放进提示词,再由模型生成答案。下面的实现只用于理解原理,语料量大时应换成 pgvector、Qdrant、Milvus 等向量库。
# rag.pyimport mathimport osimport httpxfrom llm_client import get_configdef embed(texts: list[str]) -> list[list[float]]:base_url, api_key, _ = get_config()embed_model = os.getenv("LLM_EMBED_MODEL", "")if not embed_model:raise RuntimeError("请设置 LLM_EMBED_MODEL 环境变量")resp = httpx.post(f"{base_url}/embeddings",headers={"Authorization": f"Bearer {api_key}"},json={"model": embed_model, "input": texts},timeout=30.0,)resp.raise_for_status()items = sorted(resp.json()["data"], key=lambda item: item["index"])return [item["embedding"] for item in items]def split_text(text: str, size: int = 500, overlap: int = 50) -> list[str]:step = size - overlapreturn [text[start:start + size] for start in range(0, len(text), step)]def cosine(a: list[float], b: list[float]) -> float:dot = sum(x * y for x, y in zip(a, b))norm = math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b))return dot / norm if norm else 0.0class SimpleIndex:def __init__(self):self.chunks: list[str] = []self.vectors: list[list[float]] = []def add_document(self, text: str) -> None:pieces = split_text(text)for i in range(0, len(pieces), 64): # 分批请求,批大小以厂商限制为准batch = pieces[i:i + 64]self.chunks.extend(batch)self.vectors.extend(embed(batch))def search(self, query: str, k: int = 3) -> list[str]:if not self.chunks:return []qv = embed([query])[0]ranked = sorted(zip(self.chunks, self.vectors),key=lambda pair: cosine(qv, pair[1]), reverse=True)return [chunk for chunk, _ in ranked[:k]]def build_rag_prompt(question: str, contexts: list[str]) -> str:ctx = "\n\n".join(f"[资料{i}]\n{text}" for i, text in enumerate(contexts, 1))return ("请仅依据下面的资料回答问题。资料中没有答案时,回答“资料中未提及”。\n\n"f"{ctx}\n\n问题:{question}")
使用方式是:启动时调用 index.add_document(...) 载入资料,问答时把 index.search 作为 retrieve 参数传给 answer。
RAG 效果主要取决于三件事:切分是否保留了完整语义,检索是否召回了正确片段,提示词是否约束模型只依据资料作答。上线前应准备一组带标准答案的问题,逐项检查召回结果,而不是只看几个样例。
权限控制同样重要。检索时必须过滤掉当前用户无权访问的文档,不能等模型生成后再隐藏内容。
五、工程运维层:日志、成本与可用性
运维层保证应用长期稳定运行。日志要记录模型名、耗时、Token 用量、状态码和请求编号,但不记录 API Key,也尽量不记录用户的原始隐私内容。
# ops.pyimport loggingimport timelogger = logging.getLogger("llm")def log_call(model: str, started_at: float, usage: dict, status: str) -> None:latency_ms = int((time.monotonic() - started_at) * 1000)logger.info("model=%s status=%s latency_ms=%d prompt_tokens=%s completion_tokens=%s",model, status, latency_ms,usage.get("prompt_tokens"), usage.get("completion_tokens"),)
调用前记下 time.monotonic(),调用后把返回的 usage 字段传入。非流式响应通常带有 usage。流式返回是否携带用量,取决于厂商,需查看官方文档中的相关参数。
运维还应包括以下内容:
- 为每个用户或每个租户设置调用频率和费用上限,并配置预算告警;
- 主模型连续失败时,切换到备用模型,备用模型名也放在配置中;
- 对重复的高频问题做缓存,但缓存键和内容都要考虑隐私与权限;
- 定期用固定问题集回归测试,确认模型升级后效果没有明显下降。
选型建议
| 场景 | 建议做法 | 需要关注的点 |
|---|---|---|
| 单轮问答、接口简单 | 本文的客户端加 FastAPI | 依赖少,便于调试 |
| 多轮对话、固定流程 | 自写编排层 | 历史裁剪和状态要有单元测试 |
| 文档问答、知识库 | RAG 加向量库 | 切分策略、召回质量评测 |
| 多步骤、分支与人工审核 | 图式编排框架,如 LangGraph | 学习成本,版本变化较快 |
| 快速验证 RAG 原型 | LlamaIndex、LangChain 等框架 | 抽象层多,上线前要审查实际发出的请求 |
选择模型或网关时,可以按以下维度逐项对比:模型能力、延迟、价格、SLA、数据存储与合规区域、SDK 成熟度、流式支持、可观测性。每一项都用自己的样本实测,不预设数字。
最小落地清单
- 用环境变量或密钥管理服务注入 API Key,代码和日志中不出现密钥。
- 完成第一节客户端,并验证超时和 429 的重试行为。
- 完成第二节后端和前端,确认每条事件以空行结尾,前端能逐字显示。
- 在本地用固定问题集验证输

登录后可评论,请前往 登录 或 注册