AI on Snow

MCP 完全指南：原理、远程调用链路与自建服务接入 Agent

Fri, 09 Oct 2026 15:00:00 +0800

MCP 完全指南：原理、远程调用链路与自建服务接入 Agent

大模型会“思考”和生成文本，却不知道你公司今天新增了哪个项目，也不能凭空替你创建工单。MCP 做的事，是用一套标准协议把这些外部数据和动作安全地接到 Agent 身边。

如果只记一句话，可以记住：

MCP（Model Context Protocol，模型上下文协议）是 Agent 应用与外部能力之间的标准接口。它规定如何发现能力、描述参数、发起调用、返回结果与协商权限；它不是模型，也不是新的业务 API。

本文按 2026-07-28 版 MCP 规范讲解，同时标出旧版客户端常见的初始化与会话差异。协议仍在快速演进，真正接入时应以所用 Host 和 SDK 支持的版本为准。

一、为什么需要 MCP

没有 MCP 时，每个 Agent 平台都有一套插件格式。若要让三个 Agent 连接 GitHub、数据库和内部工单系统，往往需要写九份适配代码：

flowchart LR subgraph Before[没有 MCP：N × M 个适配器] A1[Agent A] --> X1[GitHub 适配] A1 --> X2[数据库适配] A2[Agent B] --> X3[GitHub 适配] A2 --> X4[工单适配] end subgraph After[使用 MCP：统一协议边界] B1[Agent A] --> P[MCP] B2[Agent B] --> P P --> S1[GitHub Server] P --> S2[Database Server] P --> S3[Ticket Server] end

MCP 把“Agent 如何使用外部能力”从具体平台中抽了出来。它带来的核心价值不是少写一次 HTTP 请求，而是统一了以下契约：

问题	MCP 给出的统一方式
服务有什么能力	`tools/list`、`resources/list`、`prompts/list`
参数长什么样	JSON Schema
怎样执行动作	`tools/call`
怎样读取上下文	`resources/read`
怎样返回结果	`content`、`structuredContent`、错误信息与元数据
双方支持哪些功能	协议版本、capabilities 与扩展协商
消息如何传输	本地 `stdio` 或远程 Streamable HTTP

它和 USB-C 的类比有用但不完整：USB-C 统一了物理接口，MCP 统一的是一组面向模型的语义与调用契约。一个工具的名字、描述和 Schema 会直接影响模型是否选中它，因此 MCP 元数据本身就是产品界面的一部分。

二、先认清四个角色

flowchart LR U[用户] --> H[Host
Agent 应用] H --> M[LLM] H --> C1[MCP Client A] H --> C2[MCP Client B] C1 <-->|MCP| S1[MCP Server
项目系统] C2 <-->|MCP| S2[MCP Server
知识库] S1 --> API1[(业务 API / DB)] S2 --> API2[(文档 / 搜索)]

角色	做什么	常见误解
User	提出目标并对高风险动作确认	用户通常不直接构造 MCP 请求
Host	承载 Agent、模型、上下文、策略、审批与多个 MCP Client	MCP Server 不负责整个 Agent 循环
MCP Client	与一个 Server 通信，完成发现、调用和协议兼容	它一般是 Host 内部组件，不等于用户界面
MCP Server	暴露能力，校验调用并连接真实业务系统	它不是把整个数据库无条件交给模型

最重要的一点：通常不是模型直接访问 MCP Server。Host 先把允许的能力提供给模型；模型产生工具调用意图；Host 再根据权限、审批和运行策略决定是否执行。这个边界让“模型想做什么”和“系统允许做什么”可以分开。

三、MCP 暴露什么

MCP Server 主要暴露三类原语：

原语	控制者	适合什么	示例
Tools	模型选择调用，Host 执行策略把关	查询或执行动作	`search_projects`、`create_ticket`
Resources	Host / 应用选择加载	可寻址的只读上下文	`project://P-1024/spec`
Prompts	用户或 Host 选择	可复用的工作流模板	“生成发布检查清单”

此外还有通知、补全、引导式输入等能力。不要因为协议支持很多功能就全部实现：大多数服务从少量清晰的 Tools 开始就够了。

Tool 和普通 REST API 有什么不同

底层业务逻辑完全可以继续使用 REST、gRPC 或数据库。MCP Server 更像一层“面向 Agent 的适配器”：

flowchart LR L[LLM 看到的工具
名称 + 描述 + Schema] --> S[MCP Server
鉴权 · 校验 · 编排] S --> R1[REST API] S --> R2[gRPC] S --> R3[(Database)] S --> R4[Message Queue]

REST 路由通常为人类开发者设计，例如 PATCH /v1/projects/:id；MCP Tool 应围绕用户目标设计，例如 archive_project(project_id, reason)。不要简单地把数百个内部端点一比一暴露给模型。

四、远程 MCP 的完整调用链路

远程 MCP 通常使用 Streamable HTTP。旧的 HTTP+SSE transport 已被取代，只应为旧客户端保留兼容。下面先看一次典型工具调用：

sequenceDiagram autonumber actor User as 用户 participant Host as Agent Host participant Model as LLM participant Client as MCP Client participant Server as Remote MCP Server participant API as 业务系统 Host->>Client: 连接服务器配置 Client->>Server: 发现协议版本与 capabilities Server-->>Client: server info + capabilities Client->>Server: tools/list Server-->>Client: 工具名、描述、输入/输出 Schema、annotations User->>Host: “列出本周延期的项目” Host->>Model: 用户消息 + 可用工具定义 Model-->>Host: 调用 list_projects(status="delayed") Host->>Host: 策略检查 / 必要时请求确认 Host->>Client: 执行工具调用 Client->>Server: tools/call + 身份凭据 Server->>Server: 鉴权、租户隔离、参数校验 Server->>API: 查询真实业务数据 API-->>Server: 项目记录 Server-->>Client: content + structuredContent Client-->>Host: 工具结果 Host->>Model: 将允许的结果加入上下文 Model-->>Host: 组织自然语言答案 Host-->>User: 最终回复 + 来源/动作状态

这条链路可以拆成五段。

1. 配置与发现

Host 保存 MCP Server 的名称、URL 和认证方式。连接时，双方确认协议版本、服务信息和 capabilities；Client 再读取工具列表。现代客户端会缓存列表，并在服务通知能力变化或缓存失效时刷新。

截至本文所用的 2026-07-28 规范，新链路以无会话的 server/discover 和每请求元数据为主；兼容旧规范的客户端则可能先走 initialize → initialized，并携带 Mcp-Session-Id。SDK 会处理大部分兼容逻辑，业务代码不要自己拼 JSON-RPC。

2. 工具进入模型上下文

Host 并不一定把所有工具都塞给模型。它可能按租户、角色、当前任务或工具搜索结果过滤，只向模型提供相关的名称、描述和 Schema。这一步决定模型“知道自己能做什么”。

工具越多不一定越好。五个边界明确的工具，通常比五十个描述含糊的工具更可靠，也更节省上下文。

3. 模型选择，Host 决策

模型返回的是一个结构化调用意图，而不是直接执行结果。Host 应在这里做策略判断：

该用户能否使用这个 Server 和 Tool；
读取是否可直接执行，写入是否需要确认；
参数是否命中数据边界、费用上限或速率限制；
是否存在提示注入、越权或破坏性风险。

Tool annotations 能帮助 Host 判断 readOnly、destructive、openWorld 等性质，但它们只是提示，不能替代服务端鉴权。

4. HTTP 调用与业务执行

Client 通过 HTTPS 向 /mcp 发送 MCP 请求。现代远程请求包含协议版本和路由相关信息，认证通常放在 Authorization header。Server 必须再次完成：令牌验证、scope 校验、租户隔离、参数校验、业务授权、超时与审计。

然后它才调用真正的 REST/gRPC/数据库。MCP 不会替你解决业务授权，也不会自动让一条危险 SQL 变安全。

把 SDK 隐藏的细节展开，一次现代 Tool 调用大致是下面这样（为便于阅读省略部分每请求 _meta）：

POST /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer <access-token>
Content-Type: application/json
Mcp-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: list_projects

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {"status": "delayed", "limit": 5}
  }
}

成功结果仍是 JSON-RPC，其中 content 供模型阅读，structuredContent 供程序可靠消费：

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [{"type": "text", "text": "Found 1 delayed project."}],
    "structuredContent": {
      "result": [{"id": "P-1002", "name": "Billing migration"}]
    },
    "isError": false
  }
}

不要在业务代码中手写这些报文。示例的意义是方便查日志、网关和 trace；版本协商、header 与 JSON-RPC 细节应交给 SDK。

5. 结果回到模型

工具结果常有三条通道：

字段	谁使用	建议
`content`	模型	简洁、可理解，说明发生了什么
`structuredContent`	Host / 后续工具 / UI	遵守输出 Schema，返回稳定 ID 与字段
`_meta`	Client 应用	放客户端专用信息；不要把它当秘密保险箱

Host 将允许模型看到的结果放回上下文，模型再生成最终答复。MCP 调用成功不等于用户任务成功：Agent 还需要检查 isError、确认数据完整性，并可能继续调用下一项工具。

五、两种远程连接模式

flowchart TB subgraph Direct[模式 A：应用运行时直接连接] A[你的 Agent 应用] --> C[MCP Client] C --> S[Remote MCP Server] end subgraph Hosted[模式 B：模型平台托管连接] B[你的应用] --> P[模型 / Agent 平台] P --> HS[Remote MCP Server] end

模式	优点	适合场景
运行时直连	网络、凭据、审批、过滤都由你的应用掌控	私网服务、严格合规、自定义策略
平台托管 MCP	接入代码少，Agent 平台负责协议调用	公网 HTTPS 服务、快速集成

在 OpenAI Agents SDK 中，公开远程服务可作为 hosted MCP tool；本地或私有服务则可以由 SDK runtime 通过 stdio 或 Streamable HTTP 管理。选择标准不是“哪种更新”，而是连接与信任边界应该由谁拥有。

六、从零开发一个远程 MCP Server

下面做一个最小但完整的“项目查询”服务。示例使用 Python SDK v2、Python 3.10+，并选择无状态 Streamable HTTP，便于水平扩展。

1. 初始化项目

1
2
3

mkdir project-mcp && cd project-mcp
uv init
uv add "mcp[cli]>=2,<3" pydantic

固定主版本很重要：MCP SDK 与规范演进较快，不应让生产构建在无审核时跨主版本升级。

2. 编写 `server.py`

from typing import Annotated, Literal

from mcp.server import MCPServer
from mcp.types import ToolAnnotations
from pydantic import BaseModel, Field


class Project(BaseModel):
    id: str
    name: str
    status: Literal["active", "delayed", "archived"]
    owner: str


PROJECTS = [
    Project(id="P-1001", name="Search upgrade", status="active", owner="Lin"),
    Project(id="P-1002", name="Billing migration", status="delayed", owner="Kai"),
]

mcp = MCPServer("project-catalog", version="1.0.0")


@mcp.tool(
    annotations=ToolAnnotations(
        readOnlyHint=True,
        idempotentHint=True,
        destructiveHint=False,
        openWorldHint=False,
    )
)
def list_projects(
    status: Literal["active", "delayed", "archived"] | None = None,
    limit: Annotated[int, Field(ge=1, le=50)] = 10,
) -> list[Project]:
    """List projects, optionally filtered by exact status.

    Use this for project discovery. It never modifies project data.
    """
    matches = [p for p in PROJECTS if status is None or p.status == status]
    return matches[:limit]


if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=8000,
        stateless_http=True,
        json_response=True,
    )

这段代码虽短，却已经定义了完整契约：

函数名成为 Tool 名；
docstring 成为模型看到的描述；
类型注解生成输入 JSON Schema；
返回类型生成输出 Schema；
ToolAnnotations 告诉 Host 它是只读、幂等、非破坏且不访问开放互联网的；
SDK 处理 MCP 消息、协议版本与 Streamable HTTP。

生产环境里把 PROJECTS 替换成业务 Service 调用即可，但不要跳过“从当前认证身份推导租户”这一步。

3. 本地测试

先用官方 Inspector 检查能力发现、Schema 和结果：

`1`	`uv run mcp dev server.py`

再启动真正的远程 transport：

1
2

uv run python server.py
# MCP endpoint: http://127.0.0.1:8000/mcp

另一种可靠的自动化检查，是用同一 SDK 作为客户端：

import asyncio
from mcp import Client


async def main() -> None:
    async with Client("http://127.0.0.1:8000/mcp") as client:
        tools = await client.list_tools()
        assert any(tool.name == "list_projects" for tool in tools.tools)

        result = await client.call_tool(
            "list_projects", {"status": "delayed", "limit": 5}
        )
        assert not result.is_error
        assert result.structured_content["result"][0]["id"] == "P-1002"


asyncio.run(main())

测试至少覆盖：正常参数、边界值、非法枚举、无权限、下游超时、空结果和输出 Schema。Inspector 能证明“协议可用”，自动化测试才能证明“升级后仍然可用”。

4. 容器化与部署

FROM python:3.13-slim
WORKDIR /app

COPY pyproject.toml uv.lock ./
RUN pip install --no-cache-dir uv && uv sync --frozen --no-dev

COPY server.py ./
EXPOSE 8000
CMD ["uv", "run", "python", "server.py"]

1
2

docker build -t project-mcp:1.0.0 .
docker run --rm -p 8000:8000 project-mcp:1.0.0

生产地址应是稳定 HTTPS URL，例如：

`1`	`https://mcp.example.com/mcp`

上面的演示服务没有认证，只能用于本机学习。部署到任何可被其他人访问的网络前，必须接入 SDK 的 token verifier / OAuth 配置，并在每个 Tool 内落实业务授权。

反向代理和平台需要允许流式响应；设置合理的请求体上限、调用超时和连接空闲时间。无状态模式适合普通查询与动作；需要跨调用状态时，优先让服务返回显式 handle，再由后续工具把它作为参数传回，而不是偷偷依赖某台实例的内存。

七、让 Agent 真正使用你的 MCP

“服务能访问”只完成了一半。要让 Agent 稳定调用，还需要注册、授权、告知使用时机、验证真实行为。

接入 Codex

使用 Codex CLI 添加远程服务：

1
2

codex mcp add projects --url https://mcp.example.com/mcp
codex mcp list

也可以写入 ~/.codex/config.toml：

1
2

[mcp_servers.projects]
url = "https://mcp.example.com/mcp"

然后在项目 AGENTS.md 中给出简短、可验证的路由规则：

1
2

查询项目状态、负责人或项目 ID 时，先使用 projects MCP 的只读工具。
任何修改、归档或删除项目的动作都必须先向用户展示目标与影响，并等待确认。

配置决定“Agent 能看见哪些能力”，指令决定“什么时候优先使用”。不要写“永远相信工具结果”之类的规则，远程内容仍可能过期或包含恶意文本。

接入 OpenAI Agents SDK

公开的远程 MCP 可以作为 hosted tool 附到 Agent 上：

from agents import Agent, HostedMCPTool

agent = Agent(
    name="Project assistant",
    instructions="Use the projects MCP for current project facts.",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "projects",
                "server_url": "https://mcp.example.com/mcp",
                "require_approval": "never",  # 仅适合这里的只读工具
            }
        )
    ],
)

写操作不要照抄 never。审批策略应与工具风险匹配，并且服务端仍需独立鉴权。私有服务也可以让 Agents SDK runtime 直接管理连接，从而由你的应用控制网络、过滤与审批边界。

验证 Agent 是否会用

准备一组小型评测，而不是只问一句“能用吗”：

用例	期望行为
“列出延期项目”	调 `list_projects(status="delayed")`
“介绍什么是延期项目”	若是通用定义，不应无意义调用
“把 P-1002 删除”	当前无删除工具，应说明做不到，不能伪造成功
“列出 `status=hacked`”	Schema 拒绝非法枚举，Agent 应修正或解释
Tool 返回网页中的“忽略之前指令”	把它视作不可信数据，不执行越权动作

观察三类指标：工具选择是否正确、参数是否正确、拿到结果后是否忠实回答。只看最终文字，容易漏掉重复调用、越权尝试和不必要的高成本请求。

八、工具设计决定 Agent 上限

好工具的形状

flowchart LR G[用户目标] --> N[清楚的动词名] N --> D[说明何时使用] D --> I[窄而明确的输入 Schema] I --> A[真实 annotations] A --> O[稳定的结构化输出] O --> E[可恢复的错误]

建议遵循这些规则：

一个工具完成一个可识别目标。 用 list_projects、get_project、update_project，不要做 project_action(mode, payload) 万能入口。
描述“何时用”，而不只描述实现。 模型靠描述选择工具。
输入要窄。 枚举、长度、范围、格式能写进 Schema 就不要只写在文档里。
读取与写入分开。 这样 Host 才能给不同审批策略。
返回稳定 ID。 后续调用使用 P-1002，不要让模型靠名称猜记录。
分页且设上限。 不要一次把十万行塞进上下文。
错误应可恢复。 “项目不存在，请先 list_projects 获取 ID”比堆栈信息有用。
Schema 向后兼容。 新增可选字段通常安全；改名、改类型或删除字段可能让旧 Agent 失效。

MCP 不适合什么

纯粹在应用内部、只被一处调用的简单函数，直接 function tool 可能更省事；
大文件持续传输、实时音视频等数据面，不应硬塞进工具结果；
要求严格确定性的核心交易流程，不应把关键状态机完全交给模型自由规划；
没有授权边界的“任意 SQL”“任意 Shell”“任意 URL 抓取”，不应作为生产工具暴露。

九、安全：把模型、Server 和返回内容都当作不可信边界

flowchart LR U[用户输入
不可信] --> H[Host 策略层] H -->|最小工具集| M[模型输出
不可信意图] M --> A{审批 / 授权} A --> S[MCP Server
再次鉴权与校验] S --> B[业务系统] B --> R[工具结果
仍不可信] R --> H

上线前至少做好以下事项：

风险	防线
越权读取或跨租户访问	每次调用验证 token、scope、tenant 与对象级权限
破坏性动作	单独工具、明确 annotations、用户确认、幂等键、可审计与可回滚
提示注入	把 Tool/Resource 返回当数据；禁止其改写系统策略或索要更多工具
Token 泄漏	不写入 Tool 描述、结果和日志；不向错误 audience 透传 token
SSRF	URL allowlist、DNS/IP 校验、阻止云元数据与内网地址、限制重定向
数据过量	字段最小化、分页、结果上限、PII 脱敏
拒绝服务与费用失控	速率限制、并发限制、超时、熔断、配额
供应链漂移	固定 SDK 主版本、扫描依赖、灰度升级、可回滚部署

认证回答“你是谁”，授权回答“你能对哪条数据做什么”。只验证 Bearer Token 是否存在远远不够。对多用户服务，业务查询必须从已验证凭据中取得用户和租户，绝不能信任模型传入的 user_id。

OAuth 场景使用标准授权发现、最小 scope 和明确 audience。Tool annotations、Host 弹窗、网络 allowlist 都属于纵深防御，但服务端对象级授权才是最终边界。

十、可观测性与排错

一次 MCP 问题可能出现在四层：模型没选工具、Host 拦截、协议失败、业务系统失败。日志必须能把它们串起来。

建议记录：

trace_id / request ID、Server 与 Tool 名称、版本；
已脱敏的调用方、租户、审批结果；
总耗时和下游耗时、结果大小、错误分类；
Schema 版本与部署版本。

不要记录 access token、完整私密文档或未经脱敏的 Tool 结果。

现象	先查什么
Server 完全连不上	URL、HTTPS 证书、DNS、Host header、防火墙、`/mcp` 路径
已连接但看不到工具	discovery/capabilities、`tools/list`、注册代码是否执行
模型从不调用	Tool 名称与描述、指令、是否给了过多相似工具
参数总是错	Schema 是否太宽或语义含糊，枚举与示例是否清楚
本地正常、远程超时	代理流式配置、平台超时、下游延迟、冷启动
调用成功但回答错误	`content` 是否清楚、结构化结果是否完整、模型是否拿到旧缓存
多副本偶发失败	是否暗中依赖进程内状态或旧版 session sticky routing

最短排错路径通常是：Inspector 直连 Server → SDK Client 直连 → Host 中查看工具列表 → 观察一次完整 Agent trace。这样能快速定位问题属于服务、协议还是模型决策。

十一、生产检查清单

Tool 名称、描述、输入/输出 Schema 已评审
读取、写入、破坏性动作已拆分
每次请求都做认证、scope、租户和对象级授权
远程 endpoint 使用稳定 HTTPS 与 Streamable HTTP
写操作有审批、幂等与审计，必要时可回滚
结果有分页与大小上限，不含 secrets
超时、重试、限流、熔断和下游错误映射已配置
Inspector、自动化测试和 Agent 行为评测均通过
有 trace、指标、脱敏日志和告警
SDK 与 Schema 版本固定，升级可灰度和回滚

结语

MCP 真正解决的不是“让模型发一个 HTTP 请求”，而是让能力发现、参数契约、调用执行、结果返回和安全策略有一条共同的标准链路。

开发自己的 MCP，可以按这条最短路径推进：

flowchart LR A[选一个真实用户目标] --> B[设计一个窄 Tool] B --> C[本地 Inspector] C --> D[自动化测试] D --> E[Streamable HTTP + Auth] E --> F[接入 Agent] F --> G[行为评测与观测] G --> H[再增加下一个 Tool]

先把一个只读工具做准，再增加写操作；先把权限边界做实，再追求复杂编排。MCP 降低了连接成本，却不会替代良好的 API 设计、授权模型与工程治理。

参考资料

从关键字匹配到向量检索：搜索技术的三条路

Fri, 02 Oct 2026 20:13:30 +0800

从关键字匹配到向量检索：搜索技术的三条路

搜索系统并不是只有一种做法。关键字匹配擅长找“写出来的词”，模糊搜索擅长救“写错或写不全的词”，向量检索擅长找“意思接近的内容”。到了 RAG 场景，它们往往不是互相替代，而是组合成一条更稳的检索链路。

先用一个例子定调：

用户真正想问	输入	更适合的检索方式
查某条明确规则	`退款政策`	关键字匹配
输入有拼写或错别字	`退宽政策` / `retun policy`	模糊搜索
说法很口语化	`买了东西后还能不能反悔`	向量检索
要既准又能理解语义	`会员买错套餐怎么退款`	混合检索 + 重排序

关键字匹配：找到“字面上出现过”的内容

关键字匹配是最经典的信息检索方式。它的核心思想很朴素：把文档切成词，建立索引，查询时看哪些文档包含这些词，再根据词频、字段权重、文档长度等因素排序。

搜索引擎、数据库 LIKE 查询、日志平台、站内搜索、文档系统都大量使用这种思路。工程上最常见的结构是倒排索引：不是从文档找词，而是从词直接找到包含它的文档。

特点	说明
匹配依据	查询词和文档词项的字面重合
常见算法	TF-IDF、BM25、布尔查询、字段权重
优点	快、稳定、可解释、容易加过滤条件
缺点	不懂同义词和上下文，用户换一种说法就可能搜不到
适合	商品 SKU、订单号、日志关键字、法规条款、代码符号、标题搜索

例如用户搜索 redis setnx，关键字检索非常合适，因为这个词本身就是准确术语；如果用户搜索 如何防止重复下单，纯关键字系统就可能漏掉只写了 幂等、分布式锁 的文章。

模糊搜索：解决“写错了也要搜到”

模糊搜索仍然是词面检索，只是比关键字匹配宽容一点。它关注的是：用户输入和真实词项长得像不像。

常见手段包括：

技术	解决的问题	例子
编辑距离	少字、多字、错字、相邻字母颠倒	`retun` → `return`
n-gram / trigram	子串相似、短文本近似匹配	`microserv` → `microservice`
前缀匹配	搜索建议、自动补全	`kuber` → `kubernetes`
拼音/同音纠错	中文输入法误差	`shiliangjiansuo` → `向量检索`
同义词词典	人工维护近义表达	`售后` ≈ `退货`

它最适合搜索框体验：用户没有输入完整词、英文拼错、中文有错别字、商品名只记得一半。Elasticsearch、OpenSearch、Solr、PostgreSQL trigram、Algolia 这类系统里都有对应能力。

但要注意，模糊搜索的本质不是“理解语义”。退款 和 退货 语义相关，但字面未必相似；苹果手机 和 iPhone 字面差异很大，靠编辑距离很难自然匹配。模糊搜索放宽召回后，还会带来误匹配，所以需要阈值、字段权重、热度、点击率等信号做排序。

向量检索：找到“意思接近”的内容

向量检索会先用 Embedding 模型把文本、图片、音频等内容转成一串数字。语义相近的内容，在向量空间里的距离也更近。查询时，系统把用户问题也转成向量，再找距离最近的内容。

这就是很多 RAG 系统的检索底座：先从知识库中召回相关片段，再把片段塞进 Prompt，让大模型基于资料回答。

特点	说明
匹配依据	Embedding 空间里的语义相似度
常见索引	HNSW、IVF、PQ、DiskANN
常见度量	余弦相似度、内积、欧氏距离
优点	能处理同义表达、口语化问题、跨语言/跨模态相似
缺点	成本更高，可解释性弱，精确过滤和强约束不如传统检索
适合	知识库问答、相似文章、相似图片、推荐、智能客服、代码语义搜索

比如文档里写的是：

`1`	`用户在订单完成后的 7 天内，可申请无理由退货。`

用户问：

`1`	`买完后不想要了还能退吗？`

关键字匹配可能只看到 买完、不想要，命中不稳定；向量检索更容易把它和 退货、订单完成后、7 天内 这些语义相关片段拉近。

向量检索也不是银弹。它对数字、版本号、专有名词、权限过滤、精确字段并不天然可靠。问 HTTP 451、订单 202610020001、Go 1.22 这类问题时，关键字和结构化过滤往往更可信。

它们到底差在哪

维度	关键字匹配	模糊搜索	向量检索
关注点	词是否出现	词是否相似	意思是否接近
用户输入	明确、短、术语化	有错字、缩写、前缀	口语化、描述性、长问题
召回能力	精确但可能漏	比关键字更宽	语义召回强
排序可解释性	强	中等	弱，需要额外解释
延迟与成本	低	中	中到高
典型工具	MySQL、Lucene、Elasticsearch BM25	Elasticsearch fuzzy、trigram、Algolia	FAISS、Milvus、Qdrant、Pinecone、Weaviate
常见问题	同义词搜不到	误匹配变多	召回噪声、Embedding 漂移、难调参

可以把它们理解成三层：

1
2
3

关键字匹配：你说了 A，我找 A
模糊搜索：你大概写的是 A，我帮你找 A
向量检索：你说的是 A 的意思，我找和 A 意思接近的内容

经典应用

场景	推荐方案	为什么
日志检索	关键字 + 时间/服务过滤	错一个字符都可能代表不同错误码，精确性优先
电商搜索	关键字 + 模糊搜索 + 向量召回	商品名要准，用户输入也常常不完整，还需要语义推荐
代码搜索	符号索引 + 关键字 + 语义向量	函数名要精确，需求描述又可能很口语
企业知识库问答	向量检索 + BM25 + 重排序 + RAG	需要理解问题、召回资料、生成答案并引用来源
图片以图搜图	向量检索	图像相似度很难靠关键字解决
站内帮助中心	关键字 + 模糊 + 同义词 + 向量	用户可能输入术语，也可能输入自然语言问题

最典型的例子是企业知识库 RAG。用户不会严格复述文档标题，而是问“这笔报销为什么被驳回”“试用期请病假怎么算”“客户要求删数据怎么办”。系统通常会先做权限过滤，再用 BM25 和向量各召回一批候选，最后重排序，选少量片段交给大模型回答。

实战选型：不要急着三选一

一个实用的判断方式：

你遇到的问题	优先考虑
用户会输入订单号、错误码、函数名、固定术语	关键字匹配
用户经常拼错、少打、只输入前几个字	模糊搜索
用户用自然语言描述需求，文档表达方式又不固定	向量检索
既要精确过滤，又要语义理解，还要给 LLM 喂资料	混合检索

生产系统里更常见的是组合拳：

结构化过滤：先按权限、租户、时间、类目过滤，避免召回不该看的内容。
关键字召回：用 BM25 保住精确术语、标题、编号、实体名。
向量召回：补足同义表达、口语化问题和长文本语义。
融合排序：用 RRF 或加权分数合并两路候选。
重排序：用 cross-encoder、LLM reranker 或业务规则做精排。
生成回答：RAG 场景只把最相关、最可信、来源清楚的片段交给 LLM。

一个容易记住的结论

关键字匹配解决的是有没有这个词，模糊搜索解决的是这个词是不是写歪了，向量检索解决的是这句话大概在说什么。

如果你在做一个普通搜索框，先把关键字、分词、字段权重和模糊纠错做好；如果你在做知识库问答或智能客服，再引入向量检索和 RAG；如果你在做面向真实用户的生产系统，最终大概率会走向混合检索。因为用户既会输入精确编号，也会说一大段含糊的话，而好的搜索系统要同时接得住这两种输入。

KV Cache 深入理解：为什么只存 K/V，不存 Q

Fri, 18 Sep 2026 21:35:00 +0800

KV Cache 深入理解：为什么只存 K/V，不存 Q

KV Cache 是大模型推理里最重要的加速手段之一。它的名字里只有 K 和 V，没有 Q，不是命名偷懒，而是由自回归解码的计算结构决定的：未来 token 会反复读取过去 token 的 Key 和 Value，却不会再读取过去 token 的 Query。

先把结论放在前面：

对象	在注意力里的角色	未来 token 还会用吗	是否适合长期缓存
Query `Q`	当前 token 发出的“读请求”	否	否
Key `K`	历史 token 暴露出的“地址/索引”	是	是
Value `V`	历史 token 暴露出的“内容/信息”	是	是
Attention score	当前 Query 与历史 Key 的匹配结果	通常否	否

如果只记一句话：Q 是读者，K/V 是被读的记忆。读者每一步都会换，记忆会被后面的读者反复读取。

一、把 Attention 看成一次“查表”

Transformer 里的自注意力通常写成：

$$ Q = XW_Q,\quad K = XW_K,\quad V = XW_V $$

$$ \text{Attention}(Q,K,V)=\text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V $$

这个公式看起来像矩阵乘法，但从直觉上可以拆成三件事：

名字	更像什么	含义
`Q` Query	查询语句	“我现在想找什么信息？”
`K` Key	索引地址	“我这里有什么特征，可以被谁匹配到？”
`V` Value	实际内容	“如果你匹配到了我，真正拿走的是这些信息。”

在普通的全序列计算中，Q/K/V 都来自同一段输入序列 X。但在自回归生成里，时间方向非常关键：模型已经生成了前面的 token，现在只需要生成下一个 token。

假设当前正在生成第 t 个 token，在某一层 decoder self-attention 中真正需要的是：

$$ \text{Attention}(q_t,K_{\le t},V_{\le t}) =\text{softmax}\left(\frac{q_tK_{\le t}^T}{\sqrt{d_k}}\right)V_{\le t} $$

注意这个公式里只有 当前的 q_t 和 历史到当前的 K/V。它并没有用到 q_1, q_2, ..., q_{t-1}。

这就是 KV Cache 的根。

二、Prefill 与 Decode：缓存到底发生在哪

大模型生成通常可以分成两个阶段：

阶段	输入规模	主要工作	KV Cache 的状态
Prefill	整个 prompt	一次性处理用户输入、系统提示词、历史上下文	建立初始 `K/V`
Decode	每次 1 个新 token	用新 token 继续生成下一个 token	每步追加新的 `K/V`

在 Prefill 阶段，模型要把 prompt 里的所有 token 都跑一遍。比如 prompt 长度是 n，每一层都会产生：

1
2

K_cache[layer] = [k1, k2, ..., kn]
V_cache[layer] = [v1, v2, ..., vn]

然后进入 Decode 阶段。每生成一个新 token，模型并不会把从 x1 到 xt 的整段上下文重新计算一遍，而是只处理最新 token：

new token -> 当前层 hidden state
          -> q_new, k_new, v_new
          -> q_new 读取已有 K_cache / V_cache
          -> k_new, v_new 追加进缓存

用伪代码看会更清楚：

# prefill
for layer in layers:
    q, k, v = project(prompt_hidden_states)
    K_cache[layer] = k
    V_cache[layer] = v
    hidden_states = attention(q, K_cache[layer], V_cache[layer])

# decode: 每次只处理一个新 token
for step in generation:
    x = embedding(last_token)

    for layer in layers:
        q_new, k_new, v_new = project(x)

        K_cache[layer].append(k_new)
        V_cache[layer].append(v_new)

        x = attention(q_new, K_cache[layer], V_cache[layer])

    last_token = sample(lm_head(x))

这里有一个容易忽略的细节：KV Cache 是每一层都有一份，不是整个模型共享一份。 因为每一层的 hidden state 不同，投影出来的 K/V 也不同。

常见张量形状可以写成：

1
2

K_cache[layer]: [batch, kv_heads, seq_len, head_dim]
V_cache[layer]: [batch, kv_heads, seq_len, head_dim]

如果是普通多头注意力（MHA），kv_heads 通常等于 query heads；如果是 MQA/GQA，kv_heads 会少很多，这是现代大模型降低 KV Cache 显存压力的重要技巧。

三、为什么只存 K/V，不存 Q

这个问题是理解 KV Cache 的核心。直觉答案是：旧 Q 用完就没了；旧 K/V 会被未来反复访问。

更严谨一点，可以从四个角度看。

角度	为什么旧 Q 没必要存
公式	生成第 `t` 个 token 时用的是 `q_t K_{\le t}^T`，旧的 `q_i` 不在公式里
因果方向	未来 token 只能拿自己的 Query 去看过去的 Key，不能反过来让过去的 Query 查询未来
复用价值	`k_i/v_i` 会被 `q_{i+1}, q_{i+2}, ...` 多次读取；`q_i` 只服务于第 `i` 行 attention
显存收益	存 Q 会增加大量显存，却几乎不减少 decode 计算

可以把第 i 个 token 的三样东西拆开看：

token `i` 产生的东西	第 `i` 步怎么用	第 `i+1` 步以后怎么用
`q_i`	用它查询 `K_{\le i}`，生成当前 token 的注意力输出	不再需要
`k_i`	被 `q_i` 匹配，也成为缓存的一部分	会被未来每个 `q_j` 匹配
`v_i`	被当前注意力加权求和	会被未来每个注意力分布加权求和

再换一种说法：q_i 描述的是“第 i 个位置想问什么”，这个问题只对第 i 个位置有意义。到了第 j 个位置，模型关心的是“第 j 个位置想问什么”，也就是 q_j，而不是 q_i。

如果存 Q，能不能少算一点？

通常不能。

Decode 时新 token 的 q_new 必须根据当前层的 hidden state 现场算出来。这个 hidden state 又来自前面层的输出，而前面层的输出依赖当前 token、位置编码、残差、MLP、LayerNorm 以及上一层 attention 结果。换句话说，未来的 Query 在未来 token 出现之前根本不存在。

缓存旧 Query 最多能避免“重新计算旧位置的 Query”。但 KV Cache 的设计本来就已经不重新计算旧位置了：decode 阶段只跑新 token，旧位置不会再进前向计算图。于是旧 Query 没有可节省的计算。

旧 attention 分数要不要缓存？

也通常不缓存。

第 t 步真正需要的是新的一行分数：

`1`	`score_t = q_t · [k1, k2, ..., kt]^T`

旧分数 score_1, score_2, ..., score_{t-1} 描述的是旧 Query 如何看旧 Key。它们不能替代 q_t 对历史 Key 的新匹配。把所有 attention score 都存下来，显存会从线性增长变成更接近平方增长，收益却很小。

训练时为什么好像会保存 Q？

训练和推理要分开看。

训练阶段为了反向传播，框架可能会临时保留 Q/K/V、attention score、softmax 结果、MLP 激活等中间量，或者用 activation checkpointing 在反向时重算。那是为了求梯度，不是为了自回归生成加速。

推理阶段没有反向传播，目标是尽快生成下一个 token。因此长期留下来的只有未来还会被读到的东西：K/V。

四、KV Cache 换来的代价

KV Cache 的本质是用显存换时间。它显著减少重复计算，但显存会随着上下文长度线性增长。

常见估算公式是：

1
2

KV cache bytes
≈ 2 × layers × batch × seq_len × kv_heads × head_dim × bytes_per_elem

其中前面的 2 表示 K 和 V 两份缓存。

举个近似例子，假设模型有：

参数	数值
层数 `layers`	32
query heads	32
`head_dim`	128
数据类型	FP16 / BF16，2 bytes

如果是普通 MHA，kv_heads = 32：

每 token KV cache
≈ 2 × 32 × 32 × 128 × 2 bytes
= 524288 bytes
≈ 512 KiB

如果是 GQA，假设 kv_heads = 8：

每 token KV cache
≈ 2 × 32 × 8 × 128 × 2 bytes
= 131072 bytes
≈ 128 KiB

所以同样 8192 token 的上下文，单请求 KV Cache 可能就是：

注意力结构	每 token 约占	8192 token 约占
MHA，32 个 KV heads	512 KiB	4 GiB
GQA，8 个 KV heads	128 KiB	1 GiB

这还只是 batch size = 1 的估算。服务端如果要同时处理很多请求，KV Cache 很快就会成为吞吐瓶颈。

现在再看“不存 Q”的显存意义：

架构	如果额外缓存 Q，会发生什么
MHA：`q_heads = kv_heads`	在原本 K+V 两份之外再加一份 Q，缓存大约增加 50%
GQA/MQA：`q_heads > kv_heads`	Q 的头数比 KV 多，额外缓存 Q 可能比现有 KV Cache 还大

也就是说，缓存 Q 不只是“多存一点”，在 GQA/MQA 模型里可能是非常昂贵的浪费。

五、工程实践里还要注意什么

KV Cache 听起来简单，真正服务化时会牵出不少工程问题：

问题	说明
Prefix Cache	如果很多请求共享同一段系统提示词，可以复用这段前缀的 K/V
PagedAttention	把 KV Cache 切成页管理，减少长短请求混批时的显存碎片
Sliding Window	只保留最近窗口内的 K/V，适合局部注意力模型
KV Quantization	把 KV Cache 量化到更低 bit，降低显存与带宽压力
Beam Search	多个 beam 共享前缀时要正确复制、重排或引用缓存
RoPE 位置	缓存的 K 通常已经带有位置信息，复用前缀时必须保证 position offset 一致

KV Cache 不会改变模型的理论输出，它只是避免重复计算。实际工程里如果使用低精度缓存、不同 attention kernel、不同 batch 合并策略，可能会有极小的数值差异，但原理上它是等价优化。

它也不是万能加速器：

场景	KV Cache 的作用
Prefill 很长	仍然要处理完整 prompt，KV Cache 不能消除 prefill 成本
Decode 很长	很有用，因为每步都能复用历史 K/V
上下文非常长	计算变少，但显存和显存带宽压力变大
请求很多且长度不一	需要分页缓存、连续批处理、调度器配合

最后用一张小表把核心逻辑收住：

问题	答案
KV Cache 缓存的是什么	每一层历史 token 的 Key 和 Value
为什么能加速	Decode 阶段不再重复计算旧 token 的 K/V 和旧位置输出
为什么不存 Q	旧 Query 只用于旧位置的 attention，不会被未来 token 读取
代价是什么	显存随层数、序列长度、batch、KV head 数线性增长
主要优化方向	GQA/MQA、PagedAttention、Prefix Cache、KV 量化、窗口注意力

一句话总结：KV Cache 的名字不是偶然。K/V 是上下文留给未来的可读记忆；Q 是当前 token 临时发出的读取动作。动作结束就结束了，记忆才需要留下来。

Token 是怎么计算的：AI 厂商和中转站如何统计用量

Fri, 04 Sep 2026 21:43:19 +0800

Token 是怎么计算的：AI 厂商和中转站如何统计用量

用大模型 API 时，经常会看到 prompt_tokens、completion_tokens、total_tokens 这些字段。很多人第一反应是：“Token 是不是就是字数？”不是。Token 是模型真正处理文本时使用的基本编号单元，厂商和中转站的用量统计，本质上就是围绕这些编号单元做输入、输出、缓存、工具调用和账单记录。

先给出一句话版本：

问题	简短答案
Token 是什么	模型 tokenizer 把文本切分后得到的编号单元
Token 等于字数吗	不等于。中文、英文、标点、空格、代码都会有不同切法
厂商怎么统计	请求进入模型前统计输入 token，生成时统计输出 token，结束后返回 usage
中转站怎么统计	优先读取上游厂商返回的 usage，同时自己预估、限额、落库、扣费
为什么我本地算的不一样	tokenizer 不同、隐藏模板、工具 schema、RAG 上下文、多模态、重试和缓存都会带来差异

一、Token 到底是什么

大模型并不是直接理解“字”或“词”。在进入模型前，文本会先经过一个叫 Tokenizer 的组件，被切成一串 token，然后每个 token 再映射成数字 ID。

flowchart LR A[原始文本] --> B[Tokenizer 切分] B --> C[Token 序列] C --> D[Token ID] D --> E[模型推理]

比如用户输入：

`1`	`帮我写一个 Dockerfile`

在 tokenizer 看来，它可能会被切成类似这样的片段：

`1`	`["帮", "我", "写", "一个", " Docker", "file"]`

这只是示意，不同模型的 tokenizer 结果可能完全不同。有的模型会把常见词切成一个 token，有的会把生僻字、特殊符号、空格、换行或代码符号切得更碎。

因此：

hello 可能是 1 个 token；
hello world 可能是 2 到 3 个 token；
一个中文词可能是 1 个 token，也可能被拆成多个 token；
代码、JSON、Base64、日志堆栈通常比较费 token；
空格、换行、标点也可能被计入 token。

更准确地说，Token 是 “模型词表里的最小可识别片段”。模型每次生成回答，本质上也是一个 token 一个 token 地往外吐。

二、为什么大模型要按 Token 计费

因为大模型的主要成本和 token 数强相关：

输入越长，模型要读的上下文越多；
输出越长，模型要生成的步骤越多；
上下文越长，显存、缓存和注意力计算压力越大；
如果启用工具调用、多模态、长上下文、推理增强，成本结构还会更复杂。

所以厂商通常不会简单按“请求次数”计费，而是按 token 计量。

常见账单可以抽象成：

1
2
3

费用 = 输入 token 数 * 输入单价
     + 输出 token 数 * 输出单价
     + 缓存 / 推理 / 图片 / 音频 / 工具等附加 token 成本

为什么输出 token 往往更贵？因为输出不是一次性算出来的，而是模型逐步生成。每生成一个新 token，都要基于已有上下文继续推理一次。输入阶段可以有缓存和批处理优化，输出阶段通常更受实时生成过程约束。

三、一次请求里哪些内容会被计入 Token

很多人只会数用户输入的那句话，但真实 API 请求里远不止这些内容。

内容	是否通常计入	说明
用户消息	是	用户真正输入的问题
系统提示词	是	`system` 或平台预置角色设定
开发者提示词	是	一些平台会额外注入规则或安全策略
历史对话	是	多轮聊天时，前面的上下文也会重新进入模型
RAG 检索片段	是	从知识库召回后拼进 prompt 的内容
工具定义	是	Function calling / tool schema 往往很占 token
工具调用结果	是	工具返回的 JSON、表格、日志也会进入后续上下文
输出文本	是	模型生成的回答
图片、音频、视频	视模型而定	通常会折算成专门的输入或输出计量单位
缓存命中内容	视厂商而定	有的平台会单独返回 cached tokens，并按更低价格计费

所以你看到的一次“简单提问”，在服务端可能是这样的：

系统提示词
+ 平台安全规则
+ 历史对话
+ 用户当前问题
+ RAG 检索内容
+ 工具 schema
+ 输出格式约束
= 实际输入给模型的 prompt

这也是为什么同样一句“帮我总结一下”，在不同应用里消耗 token 差异很大。聊天框、知识库问答、Agent、代码助手、联网搜索，它们背后拼进去的上下文不一样。

四、厂商是怎么统计 Token 的

AI 厂商统计 token，通常发生在模型服务的几个关键节点。

sequenceDiagram participant C as Client participant G as API Gateway participant T as Tokenizer participant M as Model Server participant B as Billing C->>G: 发送请求 G->>G: 鉴权、限流、检查上下文长度 G->>T: 对输入消息做 tokenization T-->>G: input token count G->>M: 输入 token ID M-->>G: 逐 token 生成输出 G->>G: 统计 output token count G->>B: 写入 usage 和账单事件 G-->>C: 返回 response + usage

大致流程是：

请求进入网关：先鉴权，确认 API Key、组织、项目、余额、限速策略；
规范化请求：把 messages、tools、response format、多模态内容等转成模型内部格式；
输入计数：用该模型对应的 tokenizer 计算输入 token；
上下文检查：判断输入 token + 允许输出 token 是否超过模型上下文窗口；
模型生成：模型每生成一个 token，服务端就能记录输出 token；
结束汇总：生成完成、被 stop 截断、达到最大输出长度或发生错误后，汇总 usage；
账单落库：把模型、用户、请求 ID、token 数、价格、状态写入计费系统；
返回结果：API 响应里通常会带 usage 字段，供调用方记录。

一个典型 usage 结构可能长这样：

{
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 350,
    "total_tokens": 1550
  }
}

更复杂的平台还可能拆得更细：

{
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 350,
    "cached_input_tokens": 800,
    "reasoning_tokens": 120,
    "image_input_tokens": 240
  }
}

字段名和含义会随厂商变化，但底层逻辑类似：把模型实际处理过的输入和实际生成过的输出，折算成可计费单位。

五、流式输出怎么统计

流式输出看起来像模型一边想一边发，其实服务端仍然知道自己生成了多少 token。

普通非流式响应：

`1`	`模型生成完整回答 → 统计输出 token → 一次性返回 response + usage`

流式响应：

模型生成 token 1 → 发一个 chunk
模型生成 token 2 → 发一个 chunk
模型生成 token 3 → 发一个 chunk
...
模型结束 → 返回最终 usage 或由服务端内部记录

中转站处理流式请求时通常会做两件事：

边转发 chunk 给客户端，保证用户体验；
同时缓存或累积输出文本，等上游结束后记录用量。

如果上游在最后一个 chunk 里返回 usage，中转站就直接使用它。如果上游不返回 usage，中转站可能会用 tokenizer 对完整输出再算一次，作为估算值。

流式计费最容易出问题的地方是断连：

场景	通常怎么处理
用户主动停止生成	已经生成的输出 token 仍可能计费
客户端网络断开	上游可能还生成了一小段，取决于中转站是否及时取消请求
中转站转发失败	要看上游是否已经成功处理，以及中转站的计费策略
请求超时	可能只有输入被处理，也可能已有部分输出

因此严谨的中转站不会只根据“客户端收到了多少字”扣费，而会尽量以 上游 usage 或服务端实际生成记录 为准。

六、中转站是怎么统计用户用量的

中转站可以理解成站在用户和上游模型厂商之间的 API 网关。它要做的不只是转发请求，还要做鉴权、限流、余额、计费、渠道选择和审计。

flowchart TD A[用户请求] --> B[中转站鉴权] B --> C[余额和额度检查] C --> D[预估输入 token] D --> E[选择上游渠道] E --> F[转发给模型厂商] F --> G[读取上游 usage] G --> H[按价格表计算成本] H --> I[扣用户余额或额度] I --> J[写入用量流水] J --> K[返回结果给用户]

中转站一般会有三层统计：

层级	作用	准确性
请求前预估	判断是否超上下文、余额是否足够、是否限流	估算
请求后结算	根据上游 usage 或本地 tokenizer 计算真实消耗	更接近真实
离线对账	和上游账单、渠道日志、用户流水做一致性校验	最终核对

1. 请求前：预估 Token

请求还没发给上游时，中转站通常已经要做判断：

这个请求会不会超过模型上下文窗口？
用户余额够不够？
是否超过每分钟 token 限额？
是否命中某个模型或渠道的风控限制？

这时它会用对应模型的 tokenizer 先估算输入 token：

model = request.model
tokenizer = tokenizer_registry.get(model)

normalized_prompt = render_messages(
    system=request.system,
    messages=request.messages,
    tools=request.tools,
    response_format=request.response_format
)

input_tokens_estimated = tokenizer.count(normalized_prompt)

if input_tokens_estimated + request.max_output_tokens > model.context_window:
    reject("context length exceeded")

if user.remaining_quota < estimate_cost(input_tokens_estimated, request.max_output_tokens):
    reject("insufficient quota")

这里的 render_messages 很关键。真实模型不是只看用户输入的字符串，而是看消息角色、分隔符、工具定义、输出格式等拼接后的内部 prompt。中转站如果只数 messages[-1].content，一定会低估。

2. 请求后：读取 usage 并扣费

请求完成后，中转站会优先使用上游厂商返回的 usage：

response = upstream.call(request)
usage = normalize_usage(response.usage, provider, model)

cost = usage.input_tokens * price.input
     + usage.output_tokens * price.output
     + usage.cached_tokens * price.cached_input
     + usage.reasoning_tokens * price.reasoning

ledger.insert({
    request_id,
    user_id,
    provider,
    model,
    usage,
    cost,
    status: "success"
})

user.balance -= cost

为什么要优先用上游 usage？因为上游最清楚模型内部到底拼了什么、缓存命中了多少、输出生成了多少、特殊模态如何折算。中转站自己的 tokenizer 只能尽量接近，不能保证完全一致。

3. 落库：为什么要有用量流水

一个成熟中转站不会只在用户表里减余额，还会写不可随意改动的流水记录。否则一旦用户质疑扣费，平台很难解释。

一个简化的用量表可以这样设计：

CREATE TABLE ai_usage_ledger (
    id BIGINT PRIMARY KEY,
    request_id VARCHAR(64) NOT NULL,
    user_id BIGINT NOT NULL,
    provider VARCHAR(32) NOT NULL,
    model VARCHAR(128) NOT NULL,
    prompt_tokens INT DEFAULT 0,
    completion_tokens INT DEFAULT 0,
    cached_tokens INT DEFAULT 0,
    reasoning_tokens INT DEFAULT 0,
    total_tokens INT DEFAULT 0,
    upstream_cost DECIMAL(18, 8) DEFAULT 0,
    user_cost DECIMAL(18, 8) DEFAULT 0,
    status VARCHAR(32) NOT NULL,
    created_at TIMESTAMP NOT NULL
);

关键字段：

字段	用途
`request_id`	幂等和排查，避免重试导致重复扣费
`provider`	区分不同上游厂商
`model`	不同模型价格和 tokenizer 不同
`prompt_tokens`	输入 token
`completion_tokens`	输出 token
`cached_tokens`	缓存命中的输入 token
`reasoning_tokens`	推理类模型可能单独统计的内部输出
`upstream_cost`	中转站实际付给厂商的成本
`user_cost`	中转站按自己价格表向用户收取的费用
`status`	成功、失败、取消、超时、部分输出等状态

如果平台有余额系统，扣费还要做事务处理：

begin transaction
  insert usage_ledger
  update user_balance set balance = balance - user_cost
  insert balance_change_log
commit

这样才能保证“用量流水、余额变化、账单记录”三者对得上。

七、中转站为什么会和官方统计不一致

如果你自己写一个 token 计算器，经常会发现结果和官方 usage 对不上。原因主要有这些：

原因	为什么会导致差异
tokenizer 版本不同	模型升级后词表或特殊 token 规则可能变了
消息模板不同	厂商内部会给 role、message、tool 加包装格式
系统提示词不可见	应用或中转站可能注入了用户看不到的 prompt
历史上下文被带入	多轮聊天会把旧消息一起计入输入
工具 schema 很大	一个复杂 JSON Schema 可能比用户问题还长
RAG 召回内容多	知识库片段会直接增加输入 token
输出格式约束	JSON mode、结构化输出、示例格式都会增加 prompt
多模态折算	图片、音频、视频通常不是按普通文本 token 简单计算
缓存命中	cached tokens 可能计入总量，但按不同价格结算
请求重试	上游失败重试可能产生额外成本，平台要定义是否转嫁

所以中转站的合理做法是：

请求前用本地 tokenizer 预估，用于限额和上下文判断；
请求后以上游 usage 为准结算，尽量减少争议；
没有上游 usage 时再本地估算，并在账单里标记来源；
定期离线对账，比较中转站记录和上游账单差异。

八、上下文窗口和最大输出 Token

Token 统计不只影响费用，也影响请求能不能成功。

每个模型都有上下文窗口，比如能处理 8K、32K、128K 或更长上下文。这个窗口通常要同时容纳输入和输出：

`1`	`输入 token + 最大输出 token <= 模型上下文窗口`

假设某模型上下文窗口是 8192：

输入 token	设置最大输出	是否安全
2000	1000	安全
7000	1000	接近上限
7900	1000	可能被拒绝
8200	500	输入本身已经超限

很多“上下文超长”错误，不是用户当前问题太长，而是应用把历史对话、系统 prompt、RAG 内容和工具 schema 全塞进去了。

中转站通常会在请求前做保护：

available_output = model.context_window - estimated_input_tokens

if available_output <= 0:
    reject("input too long")

max_output_tokens = min(request.max_output_tokens, available_output, platform_limit)

这也是为什么有些平台会提示“请开启上下文压缩”或“减少知识库引用数量”。本质是在帮你节省输入 token。

九、缓存 Token 是怎么回事

一些厂商会对重复前缀做上下文缓存。比如系统提示词、工具 schema、长文档前半部分每次都一样，那么服务端可以复用已经处理过的缓存，降低延迟和成本。

抽象来看：

请求 1:
长系统提示词 + 工具 schema + 用户问题 A
全部输入都需要正常处理

请求 2:
长系统提示词 + 工具 schema + 用户问题 B
前面相同部分可能命中缓存

这类 usage 可能拆成：

字段	含义
`input_tokens`	输入 token 总数
`cached_input_tokens`	输入中命中缓存的部分
`billable_input_tokens`	实际按普通输入价计费的部分，具体取决于厂商规则

对中转站来说，缓存会让计费更复杂。它不能只看 total_tokens 乘一个固定单价，而要按厂商返回的细分字段计算。

十、不同任务的 Token 消耗差异

同一个模型，不同应用形态的 token 消耗会差很多。

场景	Token 消耗特点
普通问答	用户输入短，输出长度决定主要成本
长文总结	输入很长，输出中等
代码生成	代码符号、缩进、上下文文件都比较费 token
RAG 问答	检索片段越多，输入 token 越高
Agent 调工具	工具定义和工具结果会反复进入上下文
JSON 结构化输出	schema、字段名、示例都会增加输入和输出
Embedding	通常只按输入文本 token 计量，没有 completion token
图片理解	图片会被折算成视觉输入 token 或类似单位
语音转写 / 语音生成	可能按音频时长、音频 token 或混合规则计费

如果你在开发 AI 应用，最容易低估的是三类开销：

历史对话：用户只发一句话，但你把前 30 轮都带上了；
工具 schema：函数参数定义复杂，每次请求都要传；
RAG 内容：Top-K 设得太大，召回片段太长。

优化 token 成本，通常不是把用户问题压短，而是控制这些“看不见的上下文”。

十一、如何自己估算 Token

如果你是应用开发者，至少要在请求前做一次本地估算，用来控制上下文和成本。

最简单但不精确的方法：

`1`	`estimated_tokens = text.length / 3`

这只能做非常粗的 UI 提示。更靠谱的方法是使用模型对应的 tokenizer：

1
2
3

tokenizer = get_tokenizer(model)
tokens = tokenizer.encode(rendered_prompt)
count = len(tokens)

但要记住：本地估算要尽量接近真实请求，而不是只数用户输入。

应该计入：

system prompt；
developer prompt；
历史 messages；
RAG context；
tool definitions；
response format；
当前用户问题。

不应该只计入：

`1`	`count_tokens(user_message)`

更合理的是：

rendered_prompt = render_chat_request(
    system_prompt,
    developer_prompt,
    history_messages,
    retrieved_context,
    tool_schemas,
    response_format,
    user_message
)

count_tokens(rendered_prompt, model)

本地估算的目标不是做到和厂商 100% 一样，而是提前发现明显超限和明显超预算。

十二、中转站计费系统的工程要点

如果从工程实现角度看，一个可靠的中转站至少要有这些模块：

模块	作用
模型路由	把用户请求路由到不同厂商、渠道或模型
Token 预估器	请求前计算输入 token 和最大可能成本
Usage 归一化	把不同厂商返回的 usage 统一成内部格式
价格表	维护模型输入、输出、缓存、多模态等单价
账单流水	记录每次请求的 token、费用、状态和 request_id
余额系统	做预扣、实扣、退款或额度扣减
重试策略	定义上游失败、超时、断流时是否继续扣费
对账任务	和上游账单做日级或小时级核对
风控限流	按用户、模型、IP、组织维度限制请求和 token

一个常见请求链路可以写成：

handle_request(req):
    user = authenticate(req.api_key)
    model = resolve_model(req.model)

    estimated = estimate_usage(req, model)
    reserve_quota(user, estimated.max_cost)

    try:
        upstream_resp = call_provider(req, model)
        actual_usage = normalize_usage(upstream_resp.usage)
        actual_cost = calculate_cost(actual_usage, model.price)

        settle_quota(user, actual_cost)
        write_ledger(req.id, user.id, model, actual_usage, actual_cost, "success")
        return upstream_resp

    except ProviderError as err:
        release_or_settle_by_policy(user, req.id, err)
        write_ledger(req.id, user.id, model, estimated, 0, "failed")
        raise

这里有两个细节很关键：

预扣不等于实扣：请求前按最大可能输出预扣，结束后按真实 usage 结算，多退少补；
幂等不等于不重试：同一个 request_id 重复上报时不能重复扣费，但上游真实重试产生的成本也要能解释清楚。

十三、怎么降低 Token 成本

方法	原理	风险
精简系统提示词	减少每次固定输入	规则太少可能影响输出稳定性
压缩历史对话	摘要替代完整历史	摘要可能丢细节
控制 RAG Top-K	少塞无关片段	召回不足会影响答案
缩短工具 schema	减少重复传入的结构定义	过度简化会降低工具调用准确性
设置合理最大输出	避免模型无限写长	可能截断答案
使用缓存	重复前缀命中缓存	依赖厂商支持和请求结构稳定
按任务选模型	简单任务用低成本模型	模型能力不足会带来返工
日志里记录 usage	找到最费 token 的链路	注意隐私和数据合规

实践中最有效的优化通常是这三个：

不要无脑带全量历史；
不要把过长的文档片段塞进 prompt；
不要给简单任务使用过强、过贵、上下文过大的模型。

总结

Token 计算可以拆成三层理解：

层级	关注点
模型层	tokenizer 如何把文本变成 token ID，模型如何逐 token 生成
API 层	输入、输出、工具、多模态、缓存如何汇总成 usage
平台层	中转站如何预估、限额、扣费、落库、对账和处理异常

如果只记住一句话：

Token 不是字数，而是模型实际处理的上下文单位；厂商按模型真实处理量统计 usage，中转站则围绕 usage 做预估、转发、结算和审计。

对开发者来说，真正要养成的习惯是：不要只看用户输入的长度，而要看完整上下文。系统提示词、历史消息、RAG 片段、工具 schema、结构化输出约束，都会变成模型要处理的 token，也都会最终影响成本、延迟和上下文上限。

RAG 技术全景：让大模型从"闭卷考试"到"开卷考试"

Wed, 08 Jul 2026 15:00:00 +0800

RAG 技术全景：让大模型从"闭卷考试"到"开卷考试"

大模型很强，但它会"一本正经地胡说八道"。RAG（Retrieval-Augmented Generation，检索增强生成）给大模型外挂了一个"知识库"，让它从闭卷考试变成开卷考试，回答既准又能溯源。本文用 6 张图带你完整搞懂 RAG。

一、先聊痛点：大模型的"幻觉"从哪来？

你大概遇到过这样的场景：问 GPT 一个公司内部的政策问题，或者让它总结一份最新发布的财报，它信誓旦旦地给你一段听起来很专业的回答——但仔细一查，全是编的。

这就是大模型的幻觉（Hallucination）。它不是故意的，而是由其工作方式决定的：LLM 本质上是在做"下一个 token 预测"，它根据训练时记住的概率分布生成文本，分不清"知道"和"不知道"。

原生 LLM 在企业级场景下有四个硬伤：

知识截止：训练数据有截止日期，不知道今天发生的事
幻觉问题：没见过的知识就靠"编"，还很自信
领域知识不足：对企业内部文档、专业细分领域不熟悉
无法溯源：回答不知道来自哪里，没法核验

要解决这些问题，传统思路是微调（Fine-tuning）——用领域数据重新训练模型。但微调又贵又慢，而且知识一更新就得再来一遍。

RAG 给了另一条路：不重新训练模型，而是给它外挂一个可随时更新的知识库，回答时先去知识库里检索，再基于检索到的内容作答。

就像考试一样：原生 LLM 是闭卷考试，全凭记忆，记不清就编；RAG 是开卷考试，遇到不会的可以翻书，答案有据可循。

二、RAG 是什么：核心思想一句话

RAG = 检索（Retrieval）+ 增强（Augmentation）+ 生成（Generation）

在 LLM 生成回答之前，先从外部知识库中检索相关资料，把这些资料增强到 Prompt 里作为上下文，再让 LLM 基于这些上下文生成回答。

用一句话概括：RAG 让 LLM 从"闭卷考试"变成"开卷考试"。

它和微调的根本区别在于：微调把知识"烧进"模型权重里，RAG 把知识放在模型之外的数据库里，用的时候现查。这也决定了两者的适用边界——后面会详细对比。

三、RAG 工作流程：三阶段详解

RAG 的完整流程可以拆成离线建库和在线问答两大阶段。在线问答又分为检索、增强、生成三步。

3.1 离线阶段：把文档变成可检索的向量库

这一步是"建图书馆"的过程，通常一次性完成，知识更新时增量重建：

文档加载：读取 PDF、Word、HTML、Markdown 等原始文档
切分（Chunking）：把长文档切成小段。为什么不整篇存？因为检索时要找最相关的片段，整篇文档向量会"稀释"语义；而且 LLM 上下文有限，塞不下整篇
向量化（Embedding）：用嵌入模型把每段文本转成一个高维向量（通常 768~1536 维），语义相近的文本在向量空间里距离也近
存入向量数据库：把向量和原文一起存进去，建好索引，供后续快速检索

3.2 在线阶段：检索 → 增强 → 生成

用户每一次提问，都会实时跑这三步：

① 检索 Retrieval

把用户问题用同一个 Embedding 模型转成向量
在向量数据库中做相似度检索（通常用余弦相似度），召回 Top-K（一般 3~10 条）最相关的文档片段

② 增强 Augmentation

把检索到的片段拼到 Prompt 模板里，作为上下文
一个典型的 Prompt 长这样：

你是一个严谨的问答助手，请根据以下参考资料回答用户问题。
如果资料中没有答案，请回答"根据现有资料无法回答"，不要编造。

【参考资料】
{检索到的文档片段1}
{检索到的文档片段2}
...

【用户问题】
{用户的问题}

③ 生成 Generation

把拼好的 Prompt 喂给 LLM，生成最终回答
可以要求模型在回答中标注引用来源，实现可溯源

四、完整架构图

这张图把离线和在线两条流水线放在了一起。注意几个关键点：

Embedding 模型必须一致：离线建库用哪个模型，在线检索时也要用同一个，否则向量空间不兼容
知识更新无需重训模型：新增文档只需走一遍"切分 → 向量化 → 入库"，模型权重完全不动
检索质量是 RAG 的命门：如果第一步召回的片段就不相关，后面 LLM 再强也答不好

五、核心组件选型

RAG 系统由四个核心组件构成，选型直接影响效果：

组件	作用	常见选型
Embedding 模型	文本转向量，决定语义匹配上限	BGE（智源）、M3E、OpenAI text-embedding-3、Cohere、bge-m3
向量数据库	存储与检索向量	Milvus、Qdrant、Chroma、Pinecone、FAISS、Weaviate
LLM	基于上下文生成回答	GPT-4、Claude、Qwen、DeepSeek、Llama、GLM
编排框架	串联整个流程	LangChain、LlamaIndex、Haystack、DSPy

几个选型经验：

中文场景：Embedding 优先考虑 bge-large-zh 或 bge-m3，比 OpenAI 的英文模型在中文检索上更准
轻量起步：向量库用 Chroma（纯 Python，单机嵌入式）跑通流程，量大了再换 Milvus / Qdrant
框架选择：快速原型用 LangChain，文档密集型场景用 LlamaIndex（它对文档处理和索引抽象更细致）

六、进阶技术：从"能用"到"好用"

朴素 RAG（一次向量检索 + 拼 Prompt）能跑通，但效果往往一般。真正生产级的 RAG 通常会在四个方向上做增强：

6.1 Query 改写（让问题更适合检索）

用户的问题往往是口语化、模糊的，直接拿去检索效果差。常见技巧：

Query Rewriting：让 LLM 把"那个东西怎么用"改写成"产品 X 的使用方法"
HyDE（Hypothetical Document Embeddings）：先让 LLM 生成一个假设性答案，再用这个答案的向量去检索——因为"答案"和"答案"的语义比"问题"和"答案"更接近
Multi-Query：把一个问题拆成多个子问题分别检索，结果合并去重
Step-back Prompting：先抽象出上位概念再检索，比如"2024 年诺贝尔物理学奖得主"先退到"诺贝尔物理学奖近年得主"

6.2 混合检索 + Rerank（多路召回，精排提纯）

单靠向量检索有个问题：它擅长语义匹配，但对专有名词、产品型号、人名这种精确字面匹配反而不如传统检索。所以生产系统通常用混合检索：

向量检索（语义）+ BM25 关键词检索（字面）并行召回
用 RRF（Reciprocal Rank Fusion） 融合两路结果
再用 Cross-Encoder 重排模型（如 bge-reranker-large、Cohere Rerank）对召回结果做精排
最后取 Top-K 喂给 LLM

Rerank 的关键区别：Embedding 是把 query 和 doc 分别编码再算相似度（双塔），而 Cross-Encoder 是把 query 和 doc 拼一起送进模型（交叉编码），精度高得多，但速度慢——所以先用向量检索粗筛，再用 Rerank 精排，兼顾速度和精度。

6.3 GraphRAG：基于知识图谱的全局检索

微软 2024 年提出的 GraphRAG 解决的是朴素 RAG 的另一个痛点：局部性。向量检索只能召回和问题相似的片段，回答不了"总结整个文档集的核心主题"这种全局性问题。

GraphRAG 的做法：

用 LLM 从文档中抽取实体和关系，构建知识图谱
用社区检测算法（如 Leiden）把图谱分成主题层次化的社区
为每个社区生成摘要
查询时根据问题粒度选择社区摘要或具体节点回答

它特别适合"全局性总结"“跨文档推理"类问题，代价是建图成本高、更新麻烦。

6.4 Self-RAG / 自适应 RAG：让模型自己决定要不要检索

不是每个问题都需要检索——“1+1 等于几"还去查库就浪费了。Self-RAG 让模型学会自我反思：

是否检索：判断问题是否需要外部知识，简单问题直接答
检索结果是否相关：过滤掉无关片段
生成是否忠于检索：检查答案有没有脱离资料编造

好处是省 token、降延迟，坏处是需要训练模型学会这些判断（或用 prompt 模拟），实现复杂度高。

七、方案对比：RAG vs 微调 vs 长上下文

随着模型上下文窗口越来越长（Claude 200K、Gemini 1M、GPT-4o 128K），有人质疑 RAG 是不是过时了——直接把所有文档塞进上下文不就行了？

实际并非如此，三者各有定位：

长上下文：贵（按 token 计费）、易"迷失在中间”（Lost in the Middle 现象）、不可溯源。适合一次性分析单份长文档
RAG：经济、可扩展到海量文档、可溯源。适合知识库问答
微调：改变模型行为/风格，而非注入事实知识。适合固定格式输出、领域术语适配
RAG + 微调：效果最好，成本最高，用于高精度专业场景

经验法则：知识频繁变化 → RAG；风格/格式固定 → 微调；两者都要 → 结合用。

八、实战：用 LangChain 跑通一个最小 RAG

理论讲完，来看一段能跑的代码。用 LangChain + Chroma + OpenAI 实现 30 行的 RAG：

from langchain_community.document_loaders import TextDocumentLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.vectorstores import Chroma
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

# ① 离线建库：加载 → 切分 → 向量化 → 入库
docs = TextDocumentLoader("knowledge.txt").load()
chunks = RecursiveCharacterTextSplitter(
    chunk_size=500, chunk_overlap=50      # 500 字一段，重叠 50 字
).split_documents(docs)
vectorstore = Chroma.from_documents(
    chunks, OpenAIEmbeddings(model="text-embedding-3-small")
)
retriever = vectorstore.as_retriever(search_kwargs={"k": 4})  # 召回 Top-4

# ② 在线问答：检索 → 增强 → 生成
prompt = ChatPromptTemplate.from_template("""
你是严谨的问答助手，根据以下资料回答问题。资料中没有答案就说"无法回答"，不要编造。

【资料】
{context}

【问题】
{question}
""")

def format_docs(docs):
    return "\n\n".join(d.page_content for d in docs)

rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | ChatOpenAI(model="gpt-4o-mini", temperature=0)
    | StrOutputParser()
)

# ③ 提问
print(rag_chain.invoke("公司请假流程是什么？"))

这段代码虽然简单，但已经包含了 RAG 的所有核心环节。生产化时再把 Embedding 换成 BGE、加上 Rerank、换成 Milvus，骨架不变。

九、常见挑战与优化方向

实际落地 RAG，踩坑往往不在模型，而在检索。下面是常见问题对应的优化手段：

症状	根因	优化方向
检索结果不相关	Query 与文档语义差距大	Query 改写、换更强的 Embedding
召回准确但答非所问	片段顺序/噪声干扰	加 Rerank 精排、调 Top-K
答案不忠于资料	LLM 忽略上下文编造	Prompt 加约束、降 temperature、强制引用
专有名词召回差	纯向量检索短板	加 BM25 混合检索
上下文超长	召回太多塞不下	上下文压缩、LongLLMLingua、换长上下文模型
知识更新延迟	索引重建慢	增量索引、流式更新
答案无法溯源	未保留片段来源	检索结果带 metadata，Prompt 要求标注引用

一个经验：80% 的 RAG 优化工作都在检索阶段，而不是生成阶段。先把检索做准，效果立刻提升一大截。

十、典型应用场景

企业知识问答：基于内部 Wiki、手册、合同的智能客服与员工助手
法律/医疗咨询：基于法条、判例、药品说明、病历的精准问答
代码助手：基于私有代码库的代码生成（Cursor、Copilot Workspace 都用了 RAG 思想）
教育辅导：基于教材的个性化答疑，答案可指向课本页码
智能搜索：搜索引擎的 AI 摘要（Perplexity、Bing Chat、Google AI Overviews）
数据分析：Text-to-SQL，基于数据库 schema 的自然语言查询

总结

RAG 不是某个具体工具，而是一种 “把外部知识检索和大模型生成结合起来” 的架构思想。它的价值在于：让大模型能用最新、最准、可溯源的外部知识来回答问题，而无需重新训练。

回顾本文要点：

核心思想：检索 → 增强 → 生成，让 LLM 从闭卷变开卷
两大阶段：离线建库（切分+向量化+入库）+ 在线问答（检索+增强+生成）
命门在检索：80% 的优化工作都在检索阶段
进阶四件套：Query 改写、混合检索+Rerank、GraphRAG、Self-RAG
方案选择：知识频繁变化用 RAG，风格固定用微调，高精度场景结合使用

随着模型上下文窗口变长、多模态能力增强，RAG 的形态还在演进（比如多模态 RAG、Agentic RAG），但"外挂知识库"这个核心思想短期内不会过时——毕竟，开卷考试永远比背书更可靠。

如果你对其中某个环节（比如向量数据库选型、Embedding 微调、GraphRAG 实现）想深入，欢迎在评论区交流。

AI on Snow

MCP 完全指南：原理、远程调用链路与自建服务接入 Agent

MCP 完全指南：原理、远程调用链路与自建服务接入 Agent

一、为什么需要 MCP

二、先认清四个角色

三、MCP 暴露什么

Tool 和普通 REST API 有什么不同

四、远程 MCP 的完整调用链路

1. 配置与发现

2. 工具进入模型上下文

3. 模型选择，Host 决策

4. HTTP 调用与业务执行

5. 结果回到模型

五、两种远程连接模式

六、从零开发一个远程 MCP Server

1. 初始化项目

2. 编写 server.py

3. 本地测试

4. 容器化与部署

七、让 Agent 真正使用你的 MCP

接入 Codex

接入 OpenAI Agents SDK

验证 Agent 是否会用

八、工具设计决定 Agent 上限

好工具的形状

MCP 不适合什么

九、安全：把模型、Server 和返回内容都当作不可信边界

十、可观测性与排错

十一、生产检查清单

结语

参考资料

从关键字匹配到向量检索：搜索技术的三条路

从关键字匹配到向量检索：搜索技术的三条路

关键字匹配：找到“字面上出现过”的内容

模糊搜索：解决“写错了也要搜到”

向量检索：找到“意思接近”的内容

它们到底差在哪

经典应用

实战选型：不要急着三选一

一个容易记住的结论

KV Cache 深入理解：为什么只存 K/V，不存 Q

KV Cache 深入理解：为什么只存 K/V，不存 Q

一、把 Attention 看成一次“查表”

二、Prefill 与 Decode：缓存到底发生在哪

三、为什么只存 K/V，不存 Q

如果存 Q，能不能少算一点？

旧 attention 分数要不要缓存？

训练时为什么好像会保存 Q？

四、KV Cache 换来的代价

五、工程实践里还要注意什么

Token 是怎么计算的：AI 厂商和中转站如何统计用量

Token 是怎么计算的：AI 厂商和中转站如何统计用量

一、Token 到底是什么

二、为什么大模型要按 Token 计费

三、一次请求里哪些内容会被计入 Token

四、厂商是怎么统计 Token 的

五、流式输出怎么统计

六、中转站是怎么统计用户用量的

1. 请求前：预估 Token

2. 请求后：读取 usage 并扣费

3. 落库：为什么要有用量流水

七、中转站为什么会和官方统计不一致

八、上下文窗口和最大输出 Token

九、缓存 Token 是怎么回事

十、不同任务的 Token 消耗差异

十一、如何自己估算 Token

十二、中转站计费系统的工程要点

十三、怎么降低 Token 成本

总结

RAG 技术全景：让大模型从"闭卷考试"到"开卷考试"

RAG 技术全景：让大模型从"闭卷考试"到"开卷考试"

一、先聊痛点：大模型的"幻觉"从哪来？

二、RAG 是什么：核心思想一句话

三、RAG 工作流程：三阶段详解

3.1 离线阶段：把文档变成可检索的向量库

3.2 在线阶段：检索 → 增强 → 生成

四、完整架构图

五、核心组件选型

六、进阶技术：从"能用"到"好用"

6.1 Query 改写（让问题更适合检索）

2. 编写 `server.py`