搭建一套 2026 技术栈

本书开篇提出一条主线：一项能力是有生命周期的，从算力一路向上直到一个受治理的行为，而各层之间以特定的顺序相连（第 1 章）。到实践部分后段，这条主线落到一套具体的、端到端的参考架构，把前面各实战章节搭起来的零件接成一个运行中的系统。要检验的是：接缝能否说清，胶水代码能否写出，模型调用、工具、遥测、预算和虚拟密钥托管能否落到明确的契约上。

要避开的陷阱，是把本章当成第七篇全景综述。它前面的六章已经分别综述过模型（第 81 章）、服务与算力（第 82 章）、训练与微调（第 84 章）、智能体与沙箱（第 85 章）、检索（第 86 章）以及评测（第 87 章）。这里不再逐一罗列各层的选手，而是回答另一个问题：在做好那些选择之后，这些部件如何组合成一个能运行、能观测、能付费的整体？

主旨：三份契约与一条纪律

一套 2026 技术栈之所以能组合起来，并不是因为各工具在功能上达成一致，它们并没有，而是因为它们在三份传输格式契约上达成了一致。每份契约都是一个狭窄而稳定的接口，能替换它背后的东西，而无需重写它前面的东西。一旦看清一切都在这三道接缝上交汇，整套架构的轮廓就清楚了。

1. 模型调用讲 OpenAI 兼容的 HTTP 形态。 /v1/chat/completions、/v1/responses、/v1/embeddings。到 2026 年，每个服务引擎都暴露它（第 82 章），每个托管前沿 API 都提供它或近乎孪生的形态，每个网关都归一化到它。正是这一点，让一个自托管的 vLLM 模型与一个托管的 Claude 端点，能在同一个名字背后互相替换。
2. 工具与智能体流量讲 MCP。 Model Context Protocol 之于工具集成，就如同 OpenAI 形态之于模型调用：它给出公共接口，使一台工具服务器能被每个智能体框架复用（第 85 章）。到 2026 年，它已是几乎所有框架之下的默认工具层，稳定规范是 2025-11-25，一个无状态版本正处于验证窗口中。
3. 遥测讲 OpenTelemetry GenAI span。 gen_ai.* 语义约定是 LLM、检索与智能体 span 的厂商中立格式（第 87 章）。埋点一次，就能指向 Langfuse、Phoenix、Datadog 或 Grafana，而无需重新埋点。不过到 2026 年年中，这套约定仍标记为开发中，所以要把发出的 schema 版本钉死。

把这三份契约系在一起的那一条纪律，是虚拟密钥托管（virtual-key custody）。没有任何应用、智能体、评测套件或沙箱会持有原始的提供商凭据。它们持有的，是网关签发的短时效虚拟密钥，受限于一个模型白名单、一份预算与一个限流。轮换提供商密钥，或给一个失控的智能体封顶，于是成了一次服务端操作，客户端无需重新部署。同样的思路延伸到算力：密钥存在沙箱之外，提供商能按次铸造的，就作为短时效的受限令牌递达智能体，它不肯轮换的静态密钥，则以一个不透明的占位符递达、由一个终止 TLS 的出网代理换到线上，无论哪种都绝不写死在沙箱里（第 56 章）。

三份契约共同汇聚到模型网关（gateway），而本章就是写它的地方。本书没有单独的网关章节，网关正是各层交汇之处，所以它的全景，以及本章的对比表，都安放在这里。

网关：集中控制点

模型网关（也叫「LLM gateway」或「AI gateway」）是介于应用代码与它所对话的众多提供商之间的控制平面。最薄的定义，是一个讲一种 API、向外扇出到许多家的反向代理。它真正的职责，是把没人愿意散落在应用代码里的五件事集中起来：一个统一 API、密钥托管、成本核算、回退与路由，以及预算与策略。最新的网关把这一角色从纯 token 流量扩展到智能体原生协议（工具用 MCP，智能体间用 A2A），让网关成为整套技术栈流量的单一策略点。

下文所有论断都截至 2026 年年中，出处见延伸阅读。厂商性能数字本处未做独立验证。

如何选型，取决于两条比功能清单更重要的轴：先看托管 vs 自托管，再看纯 LLM vs 智能体原生。

• 当想要零基础设施、快速访问广阔目录、且能接受提供商密钥与请求元数据经过第三方时，选托管网关（OpenRouter、Cloudflare、Portkey 托管版）。最适合原型与小团队。
• 当提供商密钥必须留在自己的环境里、或需要自己掌握的数据驻留与逐请求审计时，选自托管网关（LiteLLM、agentgateway、Envoy、Bifrost）。最适合受监管行业与平台团队。
• 当路线图需要把 MCP 工具调用与智能体间流量纳入与 token 流量同一个策略点，而不想日后再把智能体治理补接到一个只懂聊天的代理上时，转向智能体原生网关（agentgateway）。

关于性能，厂商发布了惊人的延迟数字（「快 50 倍」「亚毫秒开销」），它们在不一致的条件下测得，本处未做验证。对几乎所有工作负载，提供商与模型的延迟都以数量级压过网关开销，因此逐请求的开销很少成为决定因素。在智能体负载下真正决定胜负的是吞吐上限，而这里实现语言就显出来了。笔者做过一组受控基准，在等同 CPU 预算下以无状态直通配置比较这几个网关：Python 代理（LiteLLM）在每秒约 100 至 500 个请求处饱和，逼近 1000 时崩溃；编译型网关（Rust 写的 agentgateway、Go 写的 Lux）穿过 1000 RPS 仍保持平直，而在低负载下首字节附加延迟只在个位数毫秒。两个编译型网关彼此在统计上无法区分：真正拉开的差距是 Python 对编译型，而非某一款产品压过其余各家。这是裸转发档位，不是功能对等的测试，因为生产网关还要做鉴权、计量与策略，所以在让它定夺之前，先在自己的配置上做基准。

对于想掌控自己的密钥与成本的团队，明智的默认因此是一个性能良好的编译型网关，再配一层可观测性。上面的基准里有两个领先者：agentgateway（Rust，Apache-2.0，Linux Foundation），中立的选择；以及 Lux（Go），笔者自己的网关，也是本书其余部分所接线的那套栈（第 75 章）。LiteLLM 仍有它实在的位置：最广的提供商覆盖，以及中低流量或原型场景，那里它的生态广度盖过吞吐上限。（Lux 通篇作为示范案例出现，是因为笔者造了它，而不是把它当作优于 agentgateway 的中立之选，二者在基准上打平。）

参考架构

图 88.2 把各实战章节里逐层的接线图，合并成一张图。从上到下读它，是一条请求流；从左到右读它，是那几份契约。网关是枢纽；一切需要模型、嵌入、重排或裁判调用的，都经过它。沙箱是智能体的算力接缝，与网关的模型接缝相对应。检索紧挨着智能体。评测与可观测性接到网关与 span 上。算力与编排层，是这一切运行所依赖的基础。

三件事让这套接线在生产里站得住，每一件都是主旨里的一份契约：

• 一个 base URL，OpenAI 形态。 应用、检索器（做嵌入与重排）、评测套件、裁判，统统指向同一个网关地址。换模型或加回退是配置，不是代码。一个自托管的 bge-m3 嵌入模型与一个托管的 Cohere 重排模型，能在同一道接缝后按名字寻址（第 86 章）。
• 一个工具协议，MCP。 智能体不直拨任意工具服务器。MCP 流量经过一个掌管凭据与白名单的网关，正如模型网关掌管 token 流量（第 85 章）。
• 一种遥测格式，OTel。 每个组件都发出钉在同一 schema 版本上的 gen_ai.* span，于是评测循环能读取任何轨迹（第 87 章）。

三条弧线

本书沿三条弧线搭建了这套技术栈。参考架构正是它们交汇之处。逐条走一遍，是看清整套系统如何流动的最快方式。

从聊天机器人到智能体

聊天机器人是一次模型调用：提示词进，补全出。智能体则是给这次调用套上一个执行循环：模型发出一个工具请求，运行时执行它，把结果喂回去，模型再决定下一步做什么，可能反复许多轮（第 38 章、第 41 章）。三样增补把前者变成后者，三样都出现在 图 88.2 的右侧与顶部。

• 经检索的接地。 智能体不去轻信模型的权重，而是检索当下的、私有的或权威的上下文并注入（第 44 章、第 86 章）。2026 年的共识流水线是混合搜索（BM25 加密集向量，以倒数排名融合 RRF 合并）后接一个重排器，其中嵌入与重排模型经由网关调用，于是它们像任何其他模型调用一样被计费与限额。优先用检索，而非把百万 token 的上下文窗口塞满：长上下文很贵，而 200K token 以上的价格断崖（第 76 章）往往让检索既更便宜也更忠实。
• 经 MCP 与沙箱（sandbox）的工具。 读取结果是容易的那一半。行动，运行代码、打 API、写文件，才是安全不再关乎模型、转而关乎运行时的地方（第 85 章）。网关上的越狱过滤器，对模型被诱导发出的 rm -rf 毫无办法。执行层是沙箱：一个 microVM（Firecracker，E2B、Fly、Vercel 在用）或用户态内核（gVisor，Modal 在用），它框住爆炸半径，配以默认拒绝出网、硬超时，以及对不可逆动作的人在回路关卡（第 56 章）。
• 经检查点的记忆。 一个长跑的智能体必须能从重启中幸存，所以它的状态存在一个持久化的、带检查点的存储里（LangGraph 的 checkpointer、Pydantic AI 的持久化执行），而非进程内存里（第 39 章）。正是这一点，让人能在任务中途暂停、检视并续跑。

这条约束沿这道弧线向下贯穿：智能体不可能比它之下的网关、服务与沙箱层更可靠，这恰恰是为何「持久化执行」与「检查点」成了 2026 年框架的头条功能。框架正是想借它们，从其下各层的故障中幸存下来。

从推断到训练

一套 2026 技术栈的大部分是推断：在 OpenAI 接缝后服务一个固定的模型。但挡在托管 Claude 端点前的网关地址，同样能挡在一个自托管服务的模型前，也同样能挡在一个自己训练的模型前（第 82 章、第 84 章）。从推断到训练这段路径，是从租用能力到拥有能力的路径，而网关正是让两者可互换的东西。

经济性决定落在弧线的何处。用闭源 API，就不运行推断服务器：实验室掌管批处理、KV 缓存、投机解码与加速器（第 31 章），调用方只把它们当服务档位来使用（缓存输入定价、优先级档位）。当量与掌控力足以撑起时，便跨到自托管服务（默认 vLLM，前缀密集的智能体与 RAG 流量用 SGLang），每 token 成本于是从一张厂商账单，变成一笔自己调度的 GPU 账单。沿弧线再往前，是微调（第 17 章）或后训练一个模型，并把结果服务在同一道接缝后。训练运行本身落在算力层上，由 Slurm 或带 gang 调度插件的 Kubernetes 进行 gang 调度（第 65 章、第 62 章）。

决胜变量是持续利用率。在大约半块 GPU 的稳定负载之下，无服务器或托管推断平台（Modal、Baseten、Fireworks、Together）比为闲置预留硬件付费更便宜。在它之上，neocloud 或超大规模云上的预留集群胜出。这里的下层约束，正是来自 第 5 章 的那一条：一个 token 的服务成本要永远地付下去，正是它让人愿意一次性地把一个更小的模型过度训练，这也是为何一个模型的尺寸取决于它一生将解码多少 token，而不只取决于它的训练预算。

两个价格参数会决定自建与租用的交叉点：在它之下无服务器胜出，在它之上一张固定的预留账单胜出。

import numpy as np
# 仅为示意数字（2026 年年中指示性，非真实报价）。可自由调整。
serverless_per_gpu_hour = 4.0   # 美元/GPU 小时，仅在运行时付费
reserved_per_gpu_hour   = 2.0   # 美元/GPU 小时，无论闲忙按 24/7 计费
u = np.linspace(0.01, 1.0, 100)                      # 持续利用率
serverless = serverless_per_gpu_hour * u * 24 * 30   # 按繁忙小时付费
reserved   = reserved_per_gpu_hour * 24 * 30          # 固定月账单
crossover = reserved_per_gpu_hour / serverless_per_gpu_hour
print(f"交叉利用率 = 单块 GPU 的 {crossover:.0%}")
print("低于该点 serverless 胜出，高于该点预留胜出")
import matplotlib.pyplot as plt
plt.plot(u, serverless, label="serverless / 托管（按量付费）")
plt.axhline(reserved, color="C1", label="预留（24/7 固定费用）")
plt.axvline(crossover, color="gray", ls="--")
plt.xlabel("持续利用率（单块 GPU 的比例）")
plt.ylabel("月成本（美元）")
plt.legend(); plt.title("自建 vs 租用交叉点"); plt.show()

从用量到评测

第三条弧线合上整个循环。应用发出的每一次模型与工具调用都是用量，而每一单位用量都是能观测、能打分的东西（第 87 章）。一个在公开榜单上排名靠前的模型，落到自己的产品里仍可能表现糟糕，因为基准衡量的是通用能力（第 47 章），而真正的应用跑的是一条特定提示词，叠加自有的检索上下文，运行在一个智能体循环里。

循环分成两半，在 OTel 接缝处交汇。可观测性捕获轨迹：一个请求的完整树形，每一次 LLM 调用、检索与工具调用，每个 span 上挂着输入、输出、计时、token 与成本。评测用确定性断言、基于参考的指标，以及 LLM 作为裁判（第 50 章，由第二个模型按一套校准过的评分细则给第一个打分）来为这些轨迹打分。两者相连，因为评测的对象正是所观测到的那条轨迹：一条在线裁判未通过的生产轨迹，会被提升进离线回归套件，由它为下一次发布把关（第 52 章）。因为应用、评测与裁判统统调用网关，两个模型间的 A/B 就是一条路由规则，而裁判跑在一把受限、预算封顶的虚拟密钥上。

评测路径反哺另外两条。评测数据集变成训练路径的偏好数据，失败的智能体轨迹变成加固智能体路径的固定用例。三条路径会在同一个循环里互相反馈。

选一套参考栈

不存在一套适合所有团队的技术栈，但有三种覆盖大多数团队的原型。行是各层；挑出与自身约束相符的那一列，然后顺着它往下读。这些是供改编的起点，日期为 2026 年年中，并非排名。

表格之下那条耐久的建议：尽量减少新的活动部件，把质量预算花在见效的地方（检索与重排优于更花哨的向量库，校准过的裁判优于更多基准），让每一层都经由那三份契约可寻址，于是每一层都可替换，并且永远不要把单一厂商硬编码进去。起步的原型不会是终点的原型；正是那些契约让迁移保持便宜。

接线：接缝处的代码

要紧的胶水不是工具教程，而是接缝处的代码，那寥寥几行让各层得以互换。两段代码展示了关键模式：一段把托管与自托管模型统一起来、并带回退的网关配置，以及一个用虚拟密钥指向那一个地址的智能体。

先看网关。下面的配置暴露一个别名 smart，它在一个托管模型与一个自托管模型之间做负载均衡或回退，于是应用永远不知道是谁服务了这次请求。这里给的是形态，而非某一款产品的 schema：LiteLLM 把它写成一份静态的 YAML model_list，而 agentgateway 与 Lux 则把路由策略（加权、最低延迟、轮询或回退）绑定到一把虚拟密钥上，经由 API 或仪表板配置，而不是写进文件（第 75 章）。应用看到的接缝，两种方式都一样。

# Illustrative gateway config: one alias, hosted primary with a self-hosted fallback.
# Each gateway has its own schema; this shows the shape, not a product's exact keys.
models:
  - alias: smart                  # the name the app requests
    target: anthropic/claude-opus-4-8
    api_key: ${ANTHROPIC_API_KEY} # provider secret stays server-side
  - alias: smart                  # same alias, fallback target
    target: openai/gpt-5.5
    api_key: ${OPENAI_API_KEY}
  - alias: local                  # self-hosted, behind the same seam
    target: vllm/your-open-weight-model
    base_url: http://vllm-svc:8000/v1

routing:
  smart:
    strategy: fallback            # if the hosted target fails, use the next
    fallback: [local]
    retries: 2
# Virtual keys, team budgets, and spend caps are minted out of band,
# through an admin API or dashboard, not in this file.

再看智能体。它持有的是一把网关虚拟密钥，而非提供商密钥。它检索上下文、运行一个工具，且永远不知道是哪个模型作答。这里的 MCP 工具为简洁起见放在进程内；生产中它藏在 MCP 网关后经 HTTP 暴露，而智能体代码几乎不变，这正是 MCP 作为线协议而非库 API 的全部意义（Claude Agent SDK 形态；当前 API 见 SDK 文档）。

from claude_agent_sdk import tool, create_sdk_mcp_server, query, ClaudeAgentOptions

@tool("search_docs", "Retrieve grounding context for a query", {"q": str})
async def search_docs(args):
    # 混合检索 + 重排；嵌入/重排调用也经过网关
    hits = await retriever.hybrid_search(args["q"], top_k=8)
    return {"content": [{"type": "text", "text": "\n\n".join(h.text for h in hits)}]}

server = create_sdk_mcp_server(name="rag", version="1.0.0", tools=[search_docs])

async for msg in query(
    prompt="Using the docs, summarize our refund policy and cite the source.",
    options=ClaudeAgentOptions(
        mcp_servers={"rag": server},
        allowed_tools=["search_docs"],
        # 模型访问经由网关的 base_url + 一把受限虚拟密钥解析，绝非原始提供商
        # 凭据。替换 "smart" 背后的模型，或给这个智能体的消费封顶，都是服务端
        # 改动，无需重新部署。
    ),
):
    print(msg)

评测套件以同样的纪律合上循环。一段 Promptfoo 配置把其 provider 的 apiBaseUrl 指向网关，并用一个不同的模型家族作裁判，跑在它自己的预算封顶虚拟密钥上（第 87 章）。系统里的每一道接缝，模型调用、工具调用、检索与裁判，都在同样的两个地址（模型网关与 MCP 网关）交汇，并发出同样的 span 格式。这些共同约束让这套架构成为一个真正的系统，而不是七个各自为政、只是被摆在一起的工具。

让整套栈可运维的契约

这三份契约的作用，是把整套栈的运维轴排到同一条线上。它们扩展能力：人可以组装出比任何单层都更强的系统，一个接地的、会用工具的、持久的智能体，每一步由最适合的模型支撑，每一层各司其职又仍能组合。它们保护效率：按任务路由、回退与成本封顶都活在网关配置里，于是只在某一步需要时才升级到昂贵模型，并在负载下回退而不触碰应用代码。它们保护信任：这同时落在三者之上，虚拟密钥托管、可跨厂商携带的 OTel 基座，以及把「感觉更好」变成一道发布闸门的评测循环。只有当这三者同时成立，才值得这样去接线。到 2026 年年中，那些契约已成熟到足以让三者成立，而本书开篇所讲的生命周期，从算力到一个受治理的行为，终于能端到端地贯通同一套架构。

延伸阅读

网关：

• LiteLLM 代理（成本核算、负载均衡、回退）：https://docs.litellm.ai/docs/proxy/cost_tracking、https://docs.litellm.ai/docs/proxy/reliability
• OpenRouter, "What is an LLM gateway"：https://openrouter.ai/blog/insights/llm-gateway/
• Portkey AI gateway：https://portkey.ai/buyers-guide/ai-gateway-solutions
• agentgateway：https://agentgateway.dev/ 和 https://github.com/agentgateway/agentgateway；Linux Foundation 公告：https://www.linuxfoundation.org/press/linux-foundation-welcomes-agentgateway-project-to-accelerate-ai-agent-adoption-while-maintaining-security-observability-and-governance
• Envoy AI Gateway：https://aigateway.envoyproxy.io/docs/capabilities/
• Cloudflare AI Gateway 与 Bifrost（Maxim AI）：https://github.com/maximhq/bifrost
• Lux（作者自己的网关）：https://lux.latere.ai

本章所接的各层：

• 推断服务（vLLM 解耦、结构化输出）：https://docs.vllm.ai/en/latest/ 和 https://github.com/sgl-project/sglang
• 智能体框架与 MCP：OpenAI Agents SDK https://openai.github.io/openai-agents-python/；Claude Agent SDK https://github.com/anthropics/claude-agent-sdk-python；LangGraph https://github.com/langchain-ai/langgraph；MCP 规范 https://modelcontextprotocol.io/ 与 2026 路线图 https://blog.modelcontextprotocol.io/posts/2026-mcp-roadmap/
• 沙箱（隔离模型、安全使用纪律）：E2B https://e2b.dev/；Modal https://modal.com/resources/best-code-execution-sandboxes-ai-agents；Firecracker https://firecracker-microvm.github.io/；Firecrawl 安全模型 https://www.firecrawl.dev/blog/ai-agent-sandbox；Cella（作者自己的）https://cella.latere.ai/
• 检索（混合 + 重排、pgvector）：https://github.com/pgvector/pgvector；混合搜索与 RRF 概览 https://www.digitalapplied.com/blog/hybrid-search-bm25-vector-reranking-reference-2026
• 评测与可观测性（OTel GenAI）：Promptfoo https://www.promptfoo.dev/docs/intro/；Langfuse https://langfuse.com/docs/observability/overview；OpenTelemetry GenAI 约定 https://github.com/open-telemetry/semantic-conventions-genai
• 算力与编排（自建 vs 租用、调度器）：Modal 定价 https://modal.com/pricing；SkyPilot, "Slurm vs K8s" https://blog.skypilot.co/slurm-vs-k8s/；KubeRay https://github.com/ray-project/kuberay
• 前沿模型接入层（Bedrock、Vertex、Azure）：Anthropic 模型概览 https://platform.claude.com/docs/en/about-claude/models/overview；OpenAI on Bedrock https://aws.amazon.com/bedrock/openai/；Gemini API 定价 https://ai.google.dev/gemini-api/docs/pricing