logo

大模型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 及以上版本编写。以下版本号是示例中固定的版本,升级前请做回归测试。

  1. pip install httpx==0.27.2 requests==2.32.3 fastapi==0.115.0 uvicorn==0.30.6 pydantic==2.9.2

密钥和地址通过环境变量注入,不写进代码:

  1. export LLM_BASE_URL="https://your-llm-api-endpoint/v1"
  2. export LLM_API_KEY="your-api-key"
  3. export LLM_MODEL="your-model-name"
  4. export LLM_EMBED_MODEL="your-embedding-model-name"

项目按层拆分:llm_client.py 放第一节代码,app.py 放第二节后端,index.html 放前端。启动后端:

  1. uvicorn app:app --reload

一、模型接入层:统一调用、鉴权与重试

模型接入层是应用与模型服务之间的边界,常见形态有四种:

  • HTTP API 调用:用 POST 请求发送消息列表和参数,获取返回结果。
  • SDK 调用:官方或社区 SDK 封装了鉴权、重试和流式解析,减少重复代码。
  • 多模型统一接入:通过网关或平台层屏蔽不同模型的接口差异。
  • 鉴权与配额管理:管理 API Key、访问权限、调用频率和费用额度。

业务代码不应直接散落模型请求。更稳妥的做法是抽出一个客户端,把超时、重试和模型选择集中在一处。以后切换模型、灰度发布或降级时,只改这一处。

下面是简化版客户端。它只对超时和临时性错误(429 限流、500 及以上的服务端错误)做指数退避重试。400 这类参数错误重试没有意义,直接抛出。

  1. # llm_client.py
  2. import os
  3. import time
  4. import httpx
  5. RETRYABLE_STATUS = {429, 500, 502, 503}
  6. def get_config() -> tuple[str, str, str]:
  7. base_url = os.getenv("LLM_BASE_URL", "").rstrip("/")
  8. api_key = os.getenv("LLM_API_KEY", "")
  9. model = os.getenv("LLM_MODEL", "")
  10. if not (base_url and api_key and model):
  11. raise RuntimeError("请设置 LLM_BASE_URL、LLM_API_KEY、LLM_MODEL 环境变量")
  12. return base_url, api_key, model
  13. class LLMClient:
  14. def __init__(self, base_url: str, api_key: str, model: str,
  15. timeout: float = 30.0, max_retries: int = 2):
  16. self.base_url = base_url.rstrip("/")
  17. self.api_key = api_key
  18. self.model = model
  19. self.timeout = timeout
  20. self.max_retries = max_retries
  21. def chat(self, messages: list[dict]) -> str:
  22. payload = {"model": self.model, "messages": messages, "stream": False}
  23. headers = {"Authorization": f"Bearer {self.api_key}"}
  24. for attempt in range(self.max_retries + 1):
  25. try:
  26. resp = httpx.post(
  27. f"{self.base_url}/chat/completions",
  28. json=payload,
  29. headers=headers,
  30. timeout=self.timeout,
  31. )
  32. except httpx.TimeoutException:
  33. if attempt == self.max_retries:
  34. raise
  35. time.sleep(2 ** attempt)
  36. continue
  37. if resp.status_code in RETRYABLE_STATUS and attempt < self.max_retries:
  38. time.sleep(2 ** attempt)
  39. continue
  40. resp.raise_for_status()
  41. return resp.json()["choices"][0]["message"]["content"] or ""
  42. 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: 开头。事件结尾必须是一个空行,也就是两个换行符。浏览器靠这个空行判断一条事件已经结束,缺少它,事件就不会被派发给前端。

  1. data: {"delta": "你"}
  2. data: {"delta": "好"}
  3. data: [DONE]

上面是本文约定的简化格式,并非某个厂商的标准返回。OpenAI 兼容接口的真实流式返回中,增量文本位于 choices[0].delta.content。后端负责把真实结构转换成简化格式,前端只处理一种格式。上游厂商更换时,也只需修改后端。

3. 后端:读取上游流并转发 SSE

下面的生成器从上游逐段读取增量文本。它处理了三类常见问题:choices 是数组,必须取 choices[0];部分事件没有 choices,需要跳过;content 可能为 null,需要兜底。单个无法解析的事件只记日志并跳过,不会中断整条流。

  1. # app.py
  2. import json
  3. import logging
  4. import requests
  5. from fastapi import FastAPI
  6. from fastapi.responses import StreamingResponse
  7. from pydantic import BaseModel, Field
  8. from llm_client import get_config
  9. logger = logging.getLogger(__name__)
  10. app = FastAPI()
  11. class ChatRequest(BaseModel):
  12. message: str = Field(min_length=1, max_length=4000)
  13. def upstream_deltas(messages: list[dict]):
  14. base_url, api_key, model = get_config()
  15. headers = {
  16. "Authorization": f"Bearer {api_key}",
  17. "Content-Type": "application/json",
  18. }
  19. payload = {"model": model, "messages": messages, "stream": True}
  20. with requests.post(f"{base_url}/chat/completions", headers=headers,
  21. json=payload, stream=True, timeout=(5, 60)) as resp:
  22. resp.raise_for_status()
  23. for raw_line in resp.iter_lines():
  24. if not raw_line:
  25. continue
  26. line = raw_line.decode("utf-8")
  27. if not line.startswith("data:"):
  28. continue
  29. data = line[len("data:"):].strip()
  30. if data == "[DONE]":
  31. break
  32. try:
  33. chunk = json.loads(data)
  34. except json.JSONDecodeError:
  35. logger.warning("跳过无法解析的上游事件")
  36. continue
  37. choices = chunk.get("choices") or []
  38. if not choices:
  39. continue # 统计、心跳类事件没有 choices
  40. choice = choices[0]
  41. delta = (choice.get("delta") or {}).get("content") or ""
  42. if delta:
  43. yield delta
  44. if choice.get("finish_reason"):
  45. break
  46. @app.post("/api/chat")
  47. def chat(req: ChatRequest):
  48. messages = [{"role": "user", "content": req.message}]
  49. def event_stream():
  50. try:
  51. for delta in upstream_deltas(messages):
  52. payload = json.dumps({"delta": delta}, ensure_ascii=False)
  53. yield f"data: {payload}\n\n"
  54. yield "data: [DONE]\n\n"
  55. except Exception:
  56. logger.exception("上游调用失败")
  57. payload = json.dumps({"error": "upstream_error"})
  58. yield f"data: {payload}\n\n"
  59. yield "data: [DONE]\n\n"
  60. headers = {"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}
  61. return StreamingResponse(event_stream(),
  62. media_type="text/event-stream",
  63. headers=headers)

event_stream 是同步生成器,Starlette 会把它放到线程池中迭代,所以阻塞的 requests 调用不会卡住事件循环。并发量很高时,可以改用 httpx.AsyncClient 和异步生成器。

X-Accel-Buffering: no 告诉 Nginx 关闭响应缓冲。如果反向代理开启了缓冲,前端会等到整段内容结束才一次性收到。

4. 前端:用 fetch 读取 ReadableStream

  1. <!-- index.html -->
  2. <input id="question" placeholder="输入问题">
  3. <button id="send">发送</button>
  4. <div id="output"></div>
  5. <script>
  6. async function askStream(message, onDelta) {
  7. const resp = await fetch("/api/chat", {
  8. method: "POST",
  9. headers: { "Content-Type": "application/json" },
  10. body: JSON.stringify({ message }),
  11. });
  12. if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  13. const reader = resp.body.getReader();
  14. const decoder = new TextDecoder("utf-8");
  15. let buffer = "";
  16. while (true) {
  17. const { value, done } = await reader.read();
  18. if (done) break;
  19. buffer += decoder.decode(value, { stream: true });
  20. let sep;
  21. while ((sep = buffer.indexOf("\n\n")) !== -1) {
  22. const eventText = buffer.slice(0, sep);
  23. buffer = buffer.slice(sep + 2);
  24. for (const line of eventText.split("\n")) {
  25. if (!line.startsWith("data:")) continue;
  26. const data = line.slice(5).trim();
  27. if (data === "[DONE]") {
  28. await reader.cancel();
  29. return;
  30. }
  31. const obj = JSON.parse(data);
  32. if (obj.error) throw new Error(obj.error);
  33. if (obj.delta) onDelta(obj.delta);
  34. }
  35. }
  36. }
  37. }
  38. document.getElementById("send").addEventListener("click", () => {
  39. const output = document.getElementById("output");
  40. output.textContent = "";
  41. const question = document.getElementById("question").value;
  42. askStream(question, (text) => {
  43. output.textContent += text;
  44. }).catch((err) => {
  45. output.textContent += `\n[错误] ${err.message}`;
  46. });
  47. });
  48. </script>

buffer 用来拼接跨网络包的数据。一个事件可能被切成两段到达,也可能一次到达多个事件,所以要按空行切分,而不是逐个网络包解析。

如果前端和页面不在同一个域名下,后端需要配置 CORS,并把允许的来源写成明确列表。

三、应用编排层:历史、流程与降级

模型接入层解决“怎么调用”,编排层解决“按什么顺序调用、带什么上下文”。编排层通常负责四件事:拼装系统提示词和历史消息,裁剪过长的历史,按步骤组织检索和生成,以及在某一步失败时降级。

  1. # orchestrator.py
  2. from typing import Callable, Optional
  3. from llm_client import LLMClient
  4. SYSTEM_PROMPT = "你是一名技术文档助手。回答要简洁,依据不足时明确说明。"
  5. class Conversation:
  6. def __init__(self, system_prompt: str = SYSTEM_PROMPT, max_turns: int = 10):
  7. self.system = {"role": "system", "content": system_prompt}
  8. self.history: list[dict] = []
  9. self.max_turns = max_turns # 必须大于 0
  10. def build_messages(self, user_text: str) -> list[dict]:
  11. recent = self.history[-self.max_turns * 2:]
  12. return [self.system, *recent, {"role": "user", "content": user_text}]
  13. def record(self, user_text: str, answer: str) -> None:
  14. self.history.append({"role": "user", "content": user_text})
  15. self.history.append({"role": "assistant", "content": answer})
  16. def answer(question: str, conv: Conversation, client: LLMClient,
  17. retrieve: Optional[Callable[[str], list[str]]] = None) -> str:
  18. if retrieve is None:
  19. prompt = question
  20. else:
  21. from rag import build_rag_prompt # 第四节定义
  22. prompt = build_rag_prompt(question, retrieve(question))
  23. reply = client.chat(conv.build_messages(prompt))
  24. conv.record(question, reply) # 历史只保存用户原问题,不保存检索片段
  25. return reply

历史裁剪按轮数截取。max_turns 控制上下文长度,也控制每次请求的费用。轮数够用即可,不必保留全部对话。

流程简单、步骤固定时,自己写几十行编排代码就够了,便于调试和测试。步骤多、有分支、需要人工审核或长时间等待时,再考虑图式编排框架,例如 LangGraph。

检索到的文档内容属于数据,不是指令。文档里可能混入“忽略之前的指令”之类的文字,这类提示注入要靠提示词约束和输出检查共同防范。

四、RAG 知识增强层:让模型依据自己的资料回答

RAG(检索增强生成)的流程是:切分文档、生成向量、检索相关片段、把片段放进提示词,再由模型生成答案。下面的实现只用于理解原理,语料量大时应换成 pgvector、Qdrant、Milvus 等向量库。

  1. # rag.py
  2. import math
  3. import os
  4. import httpx
  5. from llm_client import get_config
  6. def embed(texts: list[str]) -> list[list[float]]:
  7. base_url, api_key, _ = get_config()
  8. embed_model = os.getenv("LLM_EMBED_MODEL", "")
  9. if not embed_model:
  10. raise RuntimeError("请设置 LLM_EMBED_MODEL 环境变量")
  11. resp = httpx.post(
  12. f"{base_url}/embeddings",
  13. headers={"Authorization": f"Bearer {api_key}"},
  14. json={"model": embed_model, "input": texts},
  15. timeout=30.0,
  16. )
  17. resp.raise_for_status()
  18. items = sorted(resp.json()["data"], key=lambda item: item["index"])
  19. return [item["embedding"] for item in items]
  20. def split_text(text: str, size: int = 500, overlap: int = 50) -> list[str]:
  21. step = size - overlap
  22. return [text[start:start + size] for start in range(0, len(text), step)]
  23. def cosine(a: list[float], b: list[float]) -> float:
  24. dot = sum(x * y for x, y in zip(a, b))
  25. norm = math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b))
  26. return dot / norm if norm else 0.0
  27. class SimpleIndex:
  28. def __init__(self):
  29. self.chunks: list[str] = []
  30. self.vectors: list[list[float]] = []
  31. def add_document(self, text: str) -> None:
  32. pieces = split_text(text)
  33. for i in range(0, len(pieces), 64): # 分批请求,批大小以厂商限制为准
  34. batch = pieces[i:i + 64]
  35. self.chunks.extend(batch)
  36. self.vectors.extend(embed(batch))
  37. def search(self, query: str, k: int = 3) -> list[str]:
  38. if not self.chunks:
  39. return []
  40. qv = embed([query])[0]
  41. ranked = sorted(zip(self.chunks, self.vectors),
  42. key=lambda pair: cosine(qv, pair[1]), reverse=True)
  43. return [chunk for chunk, _ in ranked[:k]]
  44. def build_rag_prompt(question: str, contexts: list[str]) -> str:
  45. ctx = "\n\n".join(f"[资料{i}]\n{text}" for i, text in enumerate(contexts, 1))
  46. return (
  47. "请仅依据下面的资料回答问题。资料中没有答案时,回答“资料中未提及”。\n\n"
  48. f"{ctx}\n\n问题:{question}"
  49. )

使用方式是:启动时调用 index.add_document(...) 载入资料,问答时把 index.search 作为 retrieve 参数传给 answer。

RAG 效果主要取决于三件事:切分是否保留了完整语义,检索是否召回了正确片段,提示词是否约束模型只依据资料作答。上线前应准备一组带标准答案的问题,逐项检查召回结果,而不是只看几个样例。

权限控制同样重要。检索时必须过滤掉当前用户无权访问的文档,不能等模型生成后再隐藏内容。

五、工程运维层:日志、成本与可用性

运维层保证应用长期稳定运行。日志要记录模型名、耗时、Token 用量、状态码和请求编号,但不记录 API Key,也尽量不记录用户的原始隐私内容。

  1. # ops.py
  2. import logging
  3. import time
  4. logger = logging.getLogger("llm")
  5. def log_call(model: str, started_at: float, usage: dict, status: str) -> None:
  6. latency_ms = int((time.monotonic() - started_at) * 1000)
  7. logger.info(
  8. "model=%s status=%s latency_ms=%d prompt_tokens=%s completion_tokens=%s",
  9. model, status, latency_ms,
  10. usage.get("prompt_tokens"), usage.get("completion_tokens"),
  11. )

调用前记下 time.monotonic(),调用后把返回的 usage 字段传入。非流式响应通常带有 usage。流式返回是否携带用量,取决于厂商,需查看官方文档中的相关参数。

运维还应包括以下内容:

  • 为每个用户或每个租户设置调用频率和费用上限,并配置预算告警;
  • 主模型连续失败时,切换到备用模型,备用模型名也放在配置中;
  • 对重复的高频问题做缓存,但缓存键和内容都要考虑隐私与权限;
  • 定期用固定问题集回归测试,确认模型升级后效果没有明显下降。

选型建议

场景 建议做法 需要关注的点
单轮问答、接口简单 本文的客户端加 FastAPI 依赖少,便于调试
多轮对话、固定流程 自写编排层 历史裁剪和状态要有单元测试
文档问答、知识库 RAG 加向量库 切分策略、召回质量评测
多步骤、分支与人工审核 图式编排框架,如 LangGraph 学习成本,版本变化较快
快速验证 RAG 原型 LlamaIndex、LangChain 等框架 抽象层多,上线前要审查实际发出的请求

选择模型或网关时,可以按以下维度逐项对比:模型能力、延迟、价格、SLA、数据存储与合规区域、SDK 成熟度、流式支持、可观测性。每一项都用自己的样本实测,不预设数字。

最小落地清单

  1. 用环境变量或密钥管理服务注入 API Key,代码和日志中不出现密钥。
  2. 完成第一节客户端,并验证超时和 429 的重试行为。
  3. 完成第二节后端和前端,确认每条事件以空行结尾,前端能逐字显示。
  4. 在本地用固定问题集验证输

发表评论

活动