AI、本地AI、Token与上下文工程：从词元到可部署智能体的完整入门
摘要
研究聚焦初学者进入 AI 应用工程时最容易混淆的三个层次：模型能力、上下文组织与执行系统。方法上，文章以 Token 作为资源计量单位，以上下文窗口作为运行时工作台，再把本地部署、检索增强、工具调用、记忆、安全与评测纳入同一工程框架。结论是，可部署智能体的核心不在于把提示词写得更长，而在于用可计量的 Token 预算、可追溯的证据、可控的工具权限和可复验的评测闭环，把模型能力转化为稳定系统行为。
关键词
Token；上下文工程；本地 AI；RAG；工具调用；智能体；评测；安全边界
研究问题与方法
本文的研究问题可以表述为：当一个 AI 功能从聊天演示进入真实产品时，哪些变量决定它是否可部署、可解释、可控制。分析方法采用分层建模：先把大模型输入还原为 Token 序列，再把一次请求拆成任务、证据、状态、工具、约束与输出预算，最后用评测与观测把生成质量连接到产品验收。这个方法避免把问题简化为“模型强不强”，也避免把上下文工程误解为“尽量塞更多材料”。
上图的分析价值在于说明：Token 不是孤立概念，而是贯穿任务表达、证据注入、模型推理和工具执行的共同资源。一个简化的上线质量函数可以写成：
其中， 表示一次智能体任务的综合可用性， 表示证据覆盖度， 表示行动与用户目标的一致性， 表示验证强度， 表示 Token 消耗， 表示端到端延迟， 表示安全与越权风险。这个公式不是为了给所有系统打同一分数，而是提醒工程取舍：证据、行动和验证必须共同提高；成本、延迟和风险不能被隐藏在“模型回答不错”之后。
引言：Token 与上下文为何构成入门起点
很多人第一次接触 AI 应用，会先问模型强不强、参数有多少、是不是本地部署、能不能联网、能不能调用工具。真正做应用时，很快会发现这些问题背后都绕不开两个底层概念：Token 和上下文。
Token 可以粗略理解为模型处理文本的最小片段。它不等于中文的一个字，也不总是英文的一个词，更不是数据库里那种访问令牌。模型看到的不是“我想写一篇文章”这几个自然语言字面，而是分词器把文本切成一串数字 ID 后形成的序列。模型的每一步推理，都是在这些 ID 构成的序列上预测下一个最可能的片段。
上下文则是模型在一次请求里能看见的全部信息：系统指令、用户问题、历史对话、检索材料、工具结果、图片或文件解析内容、结构化约束、开发者提示、隐藏状态摘要，最后还包括模型已经生成出来的部分答案。所谓“模型记得什么”，在工程上通常不是玄学，而是“这次请求里放进了什么、放进的位置是否正确、是否超过上下文窗口、是否被噪音稀释”。
因此，Token 决定输入输出成本、速度、容量和压缩方式；上下文决定模型当前能不能理解任务、引用事实、保持角色、遵守边界、调用正确工具。想把 AI 从玩具聊天框做成可部署智能体，就必须先把这两件事讲清楚。
AI 应用的三层视角
为了避免把所有概念搅在一起，可以先用三层视角看 AI 应用。
第一层是模型层。它包括大语言模型、多模态模型、嵌入模型、重排模型、语音模型、图像模型等。语言模型负责理解和生成文本，多模态模型能同时处理文本和图像等输入，嵌入模型把文本变成向量，重排模型判断候选材料和问题的相关性。模型层回答的是“能力从哪里来”。
第二层是上下文层。它负责把任务、知识、历史、工具、权限、格式约束组织成模型可消费的输入。检索增强生成、长上下文管理、记忆摘要、文件解析、提示词结构、上下文缓存，都属于这一层。上下文层回答的是“模型这次具体能看见什么”。
第三层是执行层。它让模型不只是说话，而是能做事：调用搜索、读写文件、查数据库、发 HTTP 请求、运行代码、创建工单、修改日程、触发审批。执行层要处理认证、授权、审计、重试、幂等、超时、回滚和人类确认。执行层回答的是“模型的决定怎样变成真实动作”。
初学者容易把所有问题都归因于模型层：回答错了，就换更大的模型；上下文丢了，就换更长的窗口；工具没调对，就继续堆提示词。生产级应用更常见的真相是：模型层只是基础，上下文层和执行层的工程质量才决定应用能不能稳定工作。
Token 的工程含义
Token 是分词器输出的基本单位。分词器把文本转换成模型词表中的编号。例如一段中文、英文、代码、标点、空格混在一起的输入，会被切成不同长度的片段。常见分词算法包括 BPE、WordPiece、Unigram 等。不同模型使用的分词器不同，同一句话在不同模型中可能消耗不同数量的 Token。
对中文来说，Token 和字符的关系尤其容易误解。中文文本可能一个字对应一个 Token，也可能多个字合成一个 Token；英文常见词可能整体成为一个 Token，不常见词会被拆成词根或子串；代码里的空格、换行、符号、缩进也会消耗 Token。Markdown 表格、长 JSON、日志堆栈、Base64、HTML、压缩后的无空格文本，通常都会显著增加 Token 消耗。
Token 的工程意义至少有五个。
第一，Token 是上下文窗口的计量单位。模型所谓 32K、128K、1M 上下文，通常指输入和输出加起来可容纳的 Token 数，而不是汉字数或单词数。你把 100 页文档塞进请求里，模型不是按页阅读，而是按 Token 序列处理。
第二，Token 是计费和资源消耗单位。云模型通常按输入 Token、缓存 Token、输出 Token、推理模式 Token 等计费。本地模型不按 API 账单收费，但 Token 仍然决定显存、内存、吞吐、延迟和并发能力。
第三，Token 影响响应速度。输出越长，生成步数越多；上下文越长，注意力计算和 KV Cache 占用越大。即使有 FlashAttention、PagedAttention、量化和缓存优化，长上下文也不是免费资源。
第四，Token 影响信息密度。把无关日志、重复文案、低质量网页全文塞给模型，会挤掉真正重要的证据。上下文窗口越大，越需要治理噪音，而不是越能随便堆材料。
第五，Token 影响安全边界。系统指令、用户输入、检索材料、工具返回值都在同一个上下文里被模型读取。攻击者可以把“忽略上面所有规则”写进网页、邮件或文档。如果应用没有清晰的上下文分层和工具权限，Token 不只是容量问题，也是攻击面。
从下一个词预测理解大模型能力
语言模型训练的核心目标通常可以简化为：给定前面的 Token 序列，预测下一个 Token。这个描述听起来很朴素，却能产生强大的语言理解、推理、编程、翻译、总结和规划能力。
原因在于，大规模语料里包含人类表达知识、过程、因果、规则、对话、代码、数学、错误和修正的海量模式。模型为了更好地预测下一个 Token，需要在参数中压缩这些模式。它不只是记住句子，而是学到“在什么上下文下，什么回答更合理”。Transformer 架构通过自注意力机制，让模型在生成每个位置时关注前文中相关位置。现代模型又在预训练后经过指令微调、人类反馈、偏好优化、工具使用训练和安全对齐，使它更像一个可交互助手。
但这种能力有边界。模型参数中压缩的是训练期间形成的统计规律，不等于实时数据库；模型推理时能引用的是当前上下文和参数内知识，不等于它真的访问了外部系统；模型输出的是概率生成结果，不等于每一句都有可追溯证据。因此，生产应用不能只问模型“知道不知道”，还要设计证据来源、上下文注入、工具调用、答案校验和失败处理。
上下文窗口作为当前工作台
上下文窗口是模型一次请求内可处理的最大 Token 数。它像一张工作台：你可以把需求、资料、历史记录、工具说明和格式要求都放上去，但工作台有大小，放得越乱，模型越难抓住重点。
长上下文模型让很多工作变得更简单。过去需要把长文档切块检索，现在可以直接放入更大部分；过去多轮对话必须频繁摘要，现在可以保留更多原始历史；过去代码审查只能看几个文件，现在可以放入更完整的模块背景。长上下文尤其适合合同审阅、研究报告、代码库问答、会议纪要、跨文档对比等任务。
但是长上下文不等于无限记忆，也不等于准确理解。现实中会遇到几类问题。
第一是成本问题。长上下文输入更贵，本地部署时更吃内存和显存。对高并发服务来说，盲目放入长上下文会直接拖慢吞吐。
第二是注意力稀释。上下文很长时，关键事实可能被埋在大量噪音里。即使模型理论上能读取全部内容，实际生成时也可能更依赖靠近问题的材料或高显著性的材料。
第三是位置偏差。不同模型对开头、中间、结尾信息的利用能力不同。把关键约束放在上下文中间，可能不如放在结构化的系统段、任务段或证据段里稳定。
第四是冲突处理。历史对话、检索材料、工具结果、用户新指令之间可能互相矛盾。没有优先级设计时，模型只能在语义上猜测谁更可信。
第五是输出预算。很多人只看输入窗口，忘了输出也占窗口。如果请求已经把窗口塞满，模型可能没有足够余量生成完整答案。
因此，上下文工程不是“尽量塞满”，而是“用最少必要 Token，把任务、证据、约束和可执行选项放在正确位置”。
提示词工程与上下文工程的边界
提示词工程强调怎样写指令，让模型更稳定地产生目标输出。它关注角色设定、任务拆解、示例、格式、风格、约束和反例。上下文工程比提示词工程更宽，它关注整个模型输入的构造和生命周期。
一个完整上下文可能包括：系统消息、开发者消息、用户消息、对话历史、用户画像、长期记忆、短期工作状态、检索片段、文件解析结果、工具清单、工具返回值、安全策略、输出 schema、评测标准、错误重试信息。提示词只是其中一部分。
可以用一个客服智能体举例。提示词工程会写：“你是专业客服，回答要简洁礼貌，遇到退款问题先确认订单号。”上下文工程会继续追问：订单号从哪里来？用户历史工单要不要放入上下文？知识库怎么切块？退款政策有版本号吗？工具调用失败怎么告诉模型？用户上传截图如何解析？系统规则和网页内容冲突时谁优先？同一用户下一次来访是否继承上次状态？哪些字段不能暴露？哪些操作必须人工确认？
所以，提示词工程更像写一份清晰任务说明；上下文工程更像设计一套让模型在正确资料、正确权限、正确状态下工作的运行环境。
上下文工程的基本结构
一个适合初学者的上下文结构，可以分成七块。
第一块是身份与边界。告诉模型它在这个应用中扮演什么角色，服务对象是谁，能做什么，不能做什么。这里不要塞太多空泛价值观，而要写和产品有关的边界。例如医疗应用要区分健康信息和诊断建议，财务应用要区分教育内容和投资建议，企业助理要区分可读、可写、可审批操作。
第二块是任务目标。把当前轮要完成的事情说清楚。不要让模型从长历史里猜任务。多步骤任务要说明交付物是什么、成功标准是什么、是否允许追问。
第三块是事实材料。包括用户提供的文本、检索到的文档片段、工具返回的数据。事实材料要尽量带来源、时间、标题、片段位置和可信度。不要把事实和指令混在一起，避免检索材料里的恶意指令污染系统行为。
第四块是工作状态。包括已经完成的步骤、待办项、当前假设、缺失信息、失败原因。智能体做长任务时，状态比闲聊历史更重要。一个清晰状态摘要，往往比 30 轮原始对话更省 Token、更稳定。
第五块是可用工具。工具说明要包含工具用途、输入参数、输出含义、失败模式和权限限制。工具名要语义清楚，参数 schema 要紧凑明确。
第六块是输出约束。比如 Markdown、JSON schema、表格字段、引用格式、语气风格、长度范围。结构化输出越重要，越应该使用模型或框架提供的 schema 约束，而不是只靠自然语言说“请输出 JSON”。
第七块是安全与确认。告诉模型哪些外部内容不可信，哪些操作必须确认，哪些敏感信息不能输出，哪些工具只读，哪些工具会造成真实影响。更重要的是，这些规则要在执行层落实，而不是只写在提示词里。
Token 预算与资源治理
生产应用应当为每类请求设置 Token 预算。预算不是为了省钱而已，也是为了稳定性。
一个常见预算可以这样拆：系统和开发者规则 5%，用户当前请求 5%，短期历史 10%，长期记忆摘要 5%，检索证据 40%，工具结果 20%，输出保留 15%。比例不是固定公式，关键是明确优先级。
问答型应用通常把最多预算给证据片段；写作型应用会把预算给大纲、风格样例和素材；代码任务会把预算给相关文件、错误堆栈和接口定义；智能体任务会把预算给当前计划、工具结果和状态摘要。
管理预算时有几个实用原则。
不要把完整历史无脑追加。多轮对话应当保留近期关键轮次，并把远期历史压缩成可审计摘要。摘要要包含用户偏好、已确认事实、未完成目标，而不是把每轮话都复述一遍。
不要把检索结果当作越多越好。向量检索拿到 20 个片段，不代表 20 个都该进入上下文。可以先召回，再重排，再去重，再按问题类型选择 top N。相同来源的重复段落要合并，低置信片段要降权。
不要让工具结果失控。数据库查询、网页抓取、日志搜索可能返回大量内容。工具应当支持分页、字段选择、时间范围、最大返回长度。模型需要的是“足够做决定的信息”，不是原始系统的全部噪音。
为输出保留空间。长文写作、代码生成、报告生成都需要足够输出预算。否则模型可能中途截断，或者为了压缩而牺牲结构。
本地 AI 的定位
本地 AI 指模型推理、数据处理或智能体执行主要发生在用户自己控制的设备或服务器上，而不是完全依赖第三方云 API。它可以跑在个人电脑、工作站、办公室服务器、私有云、边缘设备或内网集群上。
本地 AI 不等于一定离线。很多本地 AI 应用仍然会访问互联网、调用云端模型、同步模型仓库或使用外部搜索。更准确的说法是：关键推理链路和敏感数据处理是否在本地可控边界内。
本地 AI 也不等于免费。虽然没有按 Token 付给云厂商的账单，但硬件、电费、运维、模型调优、监控、安全、升级都会产生成本。本地模型的性价比来自可控、低边际成本、隐私、定制和低延迟，而不是天然零成本。
本地 AI 更不等于弱模型。开源和开放权重模型近年进步很快，很多 7B、14B、32B、70B 级模型在编程、数学、工具调用、多语言、长上下文方面已经能承担大量生产任务。但本地模型也有现实限制：小模型更容易幻觉，量化会影响精度，长上下文吞吐会下降，工具调用格式不一定像云模型一样稳定，多模态能力和安全对齐也有差异。
因此，本地 AI 的核心不是“云或本地二选一”，而是根据数据敏感度、延迟、成本、能力和合规要求，把模型与执行边界设计清楚。很多生产架构会采用混合模式：普通任务走本地模型，复杂推理或高风险生成走云模型；敏感文档在本地嵌入和检索，最终摘要经过脱敏后再调用外部模型；开发环境本地跑，正式服务用可弹性扩容的推理集群。
本地模型的运行方式
本地 AI 入门通常会遇到几个工具路线。
Ollama 面向个人和小团队体验，模型拉取、运行、API 调用比较简单，适合快速试验聊天、嵌入、结构化输出和工具调用。LM Studio 适合桌面端可视化管理模型，也提供 OpenAI 兼容接口，便于把本地模型接入现有应用。llama.cpp 是高性能 C/C++ 推理项目，支持 GGUF 模型格式和多种量化方式，常用于 CPU、Metal、CUDA 等多平台部署。vLLM 更偏服务端高吞吐推理，支持 OpenAI 兼容服务、PagedAttention、连续批处理等能力，适合多用户并发场景。LocalAI 则提供 OpenAI 兼容的本地推理网关，常用于把多种后端统一成类似云 API 的接口。
初学时，不必一开始就搭复杂集群。可以先用 Ollama 或 LM Studio 在本机跑通聊天和嵌入，再用 llama.cpp 理解模型文件、量化和上下文参数，最后在有并发需求时考虑 vLLM 或容器化部署。真正重要的是形成一致的应用接口：聊天、嵌入、重排、工具调用、结构化输出、流式返回、超时和错误处理。只要接口清晰，底层模型可以逐步替换。
模型文件、量化与上下文长度
本地模型常见文件格式包括 safetensors、GGUF 等。safetensors 常见于训练和 Transformers 生态；GGUF 常见于 llama.cpp 生态，适合分发量化后的模型。量化是把模型权重用更低比特表示，例如 8-bit、6-bit、5-bit、4-bit，从而降低显存或内存占用。量化越重，模型越省资源，但质量可能下降，尤其在数学、代码、长上下文和细粒度格式遵守方面更明显。
选择模型时，不要只看参数量。至少要看七件事：许可证是否允许你的用途；上下文长度是否满足任务；语言能力是否覆盖中文；工具调用或结构化输出是否稳定；嵌入模型和生成模型是否匹配；推理框架是否支持；硬件能否承受目标并发。
上下文长度也不能只看模型卡片写的最大值。有些模型标称支持很长上下文，但在本地推理时你还要设置运行时参数，KV Cache 也会占用大量内存。长上下文下的质量也要实测。一个模型能“接收”128K Token，不代表它能在 128K 中间稳定找出一个细节并正确推理。
嵌入、向量库与 RAG
RAG，即检索增强生成，是把外部知识检索结果放入上下文，让模型基于证据回答。它解决的是模型知识过期、私有知识不可见、答案缺少出处的问题。
RAG 的基本流程是：把文档切成片段；用嵌入模型把片段转成向量；存入向量库；用户提问时把问题也转成向量；查找相似片段；必要时用关键词检索、过滤条件和重排模型优化结果；把证据片段放进上下文；要求模型基于证据回答并给出引用。
切块是 RAG 的第一道质量门槛。切得太碎，语义不完整；切得太长，检索不精准，也浪费 Token。更好的做法是按文档结构切块：标题、段落、列表、表格、代码块、章节层级都应保留。每个片段要带 metadata，例如文档 ID、标题、章节、页码、更新时间、权限标签。
向量检索适合语义相似，但不擅长所有问题。用户问“退款政策第 4 条是什么”时，关键词和结构化定位可能比向量相似更可靠。生产 RAG 常用混合检索：向量召回语义相关内容，BM25 或全文索引召回精确词，metadata 过滤保证权限和版本，重排模型重新评估候选片段。
RAG 的失败常见于四类情况。第一，没检到正确材料。第二，检到了但放入上下文的片段太乱。第三，模型没有被要求严格基于证据回答。第四，权限过滤缺失，导致用户看到不该看的知识。解决 RAG 问题不能只调提示词，必须回到文档解析、切块、召回、过滤、重排、引用和评测全链路。
工具调用与真实执行
工具调用是智能体的核心能力之一。模型根据用户意图和上下文，决定是否调用某个函数或外部服务，并生成符合 schema 的参数。应用执行工具后，再把结果返回给模型，模型继续判断下一步。
工具可以是只读的，例如搜索网页、查询订单、读取日历、查数据库、获取天气。也可以是有副作用的，例如发送邮件、创建订单、修改配置、删除文件、部署服务。生产系统必须严格区分这两类。只读工具可以自动调用，但写操作通常需要权限检查、用户确认、审计记录和幂等设计。
一个好的工具定义不只是函数名和参数。它还要说明何时使用、何时不要使用、参数的业务含义、返回值字段、错误码含义、权限边界、速率限制和数据敏感性。工具过多时，还需要工具路由：先让模型选择工具类别，再展开相关工具，避免把几十上百个工具一次性塞进上下文。
工具调用也不能只依赖模型“自觉”。执行层必须做强校验：schema 校验、枚举值限制、路径限制、SQL 参数化、文件权限检查、网络域名白名单、危险操作二次确认。模型可以提出行动计划，但真正执行的是应用代码，责任边界在应用方。
智能体的循环、状态与判断
智能体不是“加一句你是智能体”就成立。一个可部署智能体至少要具备四个能力。
第一，理解目标。它能把用户目标拆成可执行步骤，并识别缺失信息。第二，维护状态。它知道已经做了什么、下一步做什么、失败在哪里。第三，使用工具。它能选择工具、传入参数、读取结果、修正计划。第四，停止和交付。它知道什么时候应该继续，什么时候应该问人，什么时候应该输出最终结果。
典型智能体循环是：接收目标；生成计划；选择下一步；调用工具；观察结果；更新状态；判断是否完成；输出结果或继续。ReAct 思路把 reasoning 和 acting 结合起来，Toolformer 等研究说明模型可以学习在合适时机使用工具。现代商业和开源框架把这些能力封装成 agent runtime、tool registry、memory、trace、handoff、guardrail 等组件。
但生产智能体最难的不是循环，而是边界。没有边界的智能体会陷入无限尝试、重复调用、误删数据、泄露隐私或把工具错误当成事实。工程上要设置最大步数、最大耗时、最大成本、工具调用频率、可访问资源范围、失败退避、人类确认点和完整审计。
结构化输出与可靠接口
很多 AI 应用最终需要的不是一段漂亮话，而是结构化结果：分类标签、JSON 对象、表单字段、SQL 查询、函数参数、工作流节点、配置文件。自然语言提示“请输出 JSON”在简单场景可用，但在生产场景不够可靠。
更稳的方式是使用模型 API 或框架支持的结构化输出能力，例如 JSON schema、工具参数 schema、受约束解码或输出解析校验。应用收到模型输出后，还要做二次校验。校验失败时，可以把错误反馈给模型让它修正，也可以降级到人工处理。
结构化输出设计要避免两个极端。字段太少，业务信息不足；字段太多，模型容易填错。字段名要业务化，不要使用只有开发者懂的内部缩写。枚举要明确，日期、金额、单位、语言、置信度、来源都要规范。对用户可见的内容和系统内部字段要分开，避免把调试信息暴露到界面。
记忆治理
“记忆”在 AI 应用里有多种含义。短期记忆通常是当前对话历史和工作状态；长期记忆是跨会话保留的用户偏好、项目背景、业务事实；外部知识库是可检索文档；工具状态是数据库或系统里的真实记录。不要把它们混为一谈。
短期记忆适合放在上下文里，帮助模型保持连贯。长期记忆应当结构化存储，并在相关时检索注入。外部知识库应当保留来源和权限。真实业务状态应当以数据库为准，而不是相信模型记忆。
记忆还涉及隐私和控制权。用户应该知道哪些信息被记住，能查看、修改、删除。敏感信息不应随意写入长期记忆。记忆注入上下文时，也要按最小必要原则，只放和当前任务相关的内容。
提示注入、数据泄露与越权工具
AI 应用的安全问题不只是模型说错话。对上下文工程来说，最典型风险是提示注入。攻击者把恶意指令写进网页、邮件、PDF、知识库、代码注释或工具返回值，诱导模型忽略原规则、泄露系统提示、调用危险工具或输出敏感信息。
防护提示注入不能靠一句“不要被提示注入攻击”。应当从结构上隔离来源：系统指令是高优先级规则；用户输入是任务请求；外部文档是非可信数据；工具返回值是观察结果，不是指令。模型可以阅读外部文档中的内容，但不应执行其中的命令，除非这些命令来自可信控制面并经过权限校验。
另一个风险是敏感信息泄露。系统提示、API Key、内部 URL、用户隐私、商业数据都可能因为上下文拼接不当进入模型输入或输出。生产系统要做密钥隔离、日志脱敏、最小权限、访问控制、数据保留策略和输出过滤。
第三个风险是工具越权。模型可能构造危险参数，例如读取任意文件路径、访问内网地址、执行 shell 命令、删除资源。工具层必须把模型当作不可信调用者：参数白名单、路径沙箱、网络访问控制、只读默认、写操作确认、审计追踪都不能省。
OWASP LLM Top 10、NIST AI 风险管理框架和主流厂商安全文档都强调类似原则：识别外部内容不可信，隔离权限，记录可追溯证据，把人类监督放在高风险环节。
评测作为产品验收机制
生产 AI 应用要有评测集。评测集不一定一开始很大，但要覆盖真实任务：常见问题、边界问题、长上下文问题、冲突材料、工具失败、权限限制、中文表达、格式输出、安全攻击。每次换模型、改提示词、调整切块、升级向量库，都应该跑一遍核心评测。
评测可以分为离线和在线。离线评测用固定样本比较准确性、引用命中、格式合规、工具选择、成本和延迟。在线评测观察真实用户满意度、重试率、人工接管率、工具失败率、幻觉反馈、转化率。对 RAG 应用，还要分别评测检索和生成：检索没命中时，生成再强也没用。
不要只用“模型自评”当唯一标准。模型可以帮忙打分，但关键样本要有人类标注或规则校验。对于结构化输出、工具调用和权限边界，自动测试比主观评分更可靠。
可观测性与决策追踪
AI 应用上线后，需要记录足够的运行证据。至少包括：请求 ID、用户任务、模型版本、输入 Token、输出 Token、检索片段 ID、工具调用参数和结果摘要、错误信息、耗时、成本、最终输出、用户反馈。对于智能体，还要记录每一步计划、工具调用、观察、状态更新和停止原因。
这些日志不是为了窥探用户隐私，而是为了调试、审计和改进。日志要做脱敏和权限控制。对敏感行业，可能还需要数据留存期限、合规审查和可删除能力。
OpenTelemetry 等通用观测体系可以用于服务链路，AI 框架也逐渐提供 trace、span、run、step 等概念。无论用什么工具，目标都一样：当用户说“它为什么这么回答”或“它有没有真的查数据库”时，工程团队能拿出证据，而不是猜。
从聊天框到可部署智能体的路线
可以按五个阶段推进。
第一阶段，单轮问答。选一个模型，设计基础系统提示，处理输入输出，支持流式返回，记录 Token 和错误。目标是让模型稳定回答一个明确任务。
第二阶段，结构化输出。给模型加 schema，校验返回结果，失败时重试或降级。目标是让模型输出能被程序消费。
第三阶段，RAG。接入文档解析、切块、嵌入、向量库、检索、重排和引用。目标是让模型基于可追溯材料回答，而不是凭印象。
第四阶段，工具调用。接入只读工具，再接入低风险写工具。目标是让模型能完成真实动作，同时保持权限和审计。
第五阶段，智能体运行时。加入计划、状态、循环、最大步数、人工确认、任务队列、可观测性和评测。目标是让模型能处理多步骤任务，并在失败时给出可理解交付。
每个阶段都应该有验收标准。例如 RAG 阶段不能只看“回答像不像”，要看引用是否命中；工具阶段不能只看“模型说已完成”，要看外部系统状态是否真的改变；智能体阶段不能只看“跑完了”，要看每一步是否可追溯、是否遵守权限。
最小可行架构
一个入门但不玩具化的架构可以这样设计。
前端负责收集用户目标、展示对话、展示引用、显示工具确认和任务进度。后端负责认证、会话、上下文构造、模型调用、工具执行和日志。模型网关统一接入云模型和本地模型，暴露聊天、嵌入、重排、结构化输出能力。知识服务负责文件上传、解析、切块、向量化、检索和权限过滤。工具服务封装业务系统 API，不让模型直接访问数据库或内网。观测服务记录 trace、成本、错误和用户反馈。
这样的架构看起来比直接调一个聊天 API 复杂，但它把责任边界分清楚了。模型负责理解和生成；上下文构造器负责给模型正确材料；工具服务负责安全执行；业务系统仍然保持权威数据；日志系统负责追溯。
常见误区
误区一：提示词越长越专业。事实上，长而空泛的提示词会浪费 Token，并让关键规则变得不突出。好的系统提示应该短、准、和产品边界相关。
误区二：上下文越大越不需要 RAG。长上下文能减少检索复杂度，但不能替代权限过滤、版本控制、引用追踪和成本治理。很多企业知识库仍然需要 RAG。
误区三：本地模型天然安全。本地部署减少第三方数据暴露，但如果本地服务没有认证、工具没有权限、日志泄露敏感信息，一样不安全。
误区四：智能体能自动解决所有问题。智能体能做多步骤任务，但也会放大错误。越能做事，越需要边界、确认和审计。
误区五：模型升级一定带来应用升级。模型更强不代表上下文构造更好。很多质量问题来自文档切块、检索、工具 schema、状态管理和 UI 交互。
初学者实践路径
如果你想真正入门，可以按下面顺序动手。
先用一个云模型或本地模型跑通最小聊天接口，记录每次请求的输入输出 Token。然后找一个分词工具，观察中文、英文、代码、Markdown 表格分别怎样消耗 Token。接着设计一个固定上下文模板，把系统规则、用户任务、证据材料、输出格式分开。再接入一个嵌入模型和向量库，用十篇自己的文档做 RAG，要求答案必须带引用。之后添加一个只读工具，例如查询天气或查本地数据库。最后再添加一个需要确认的写工具，例如创建待办事项。
每一步都要问三个问题：模型看见了什么？模型为什么这样做？外部系统是否真的发生了变化？如果这三个问题答不清楚，说明还停留在演示阶段，没有进入可部署阶段。
面向未来的理解框架
AI 技术变化很快。上下文窗口会变大，模型会更便宜，本地推理会更快，多模态会更普及，智能体框架会更成熟。但底层工程问题不会消失：信息怎样进入模型，模型怎样选择行动，行动怎样被安全执行，结果怎样被验证。
把 AI 看成一个“概率生成黑盒”，会让应用停留在聊天层。把 AI 看成一个由模型、上下文、工具、权限、状态和观测组成的系统，才可能做出生产级智能体。Token 是这个系统的计量单位，上下文是这个系统的工作台，本地 AI 是这个系统的可控部署方式，智能体是这个系统的执行形态。
入门的关键不是背术语，而是建立工程直觉：少放噪音，多放证据；少写空话，多建边界；少相信一次回答，多看完整链路；少让模型直接碰危险资源，多让工具层负责执行；少追逐模型名，多验证真实任务。
做到这里，你就不再只是“会问 AI”，而是在学习怎样把 AI 组织成一个可靠的软件系统。
资料问答助手的验收案例
假设你要给一个培训机构做资料问答助手，资料包括课程大纲、报名规则、退费条款、教师介绍和常见问题。最粗糙的做法是把这些文件上传给模型，然后让模型自由回答。它可能在演示时表现不错，但很快会出问题：用户问退费截止时间，模型引用了旧规则；用户问某位老师是否授课，模型把另一个校区的信息混进来；用户追问“那我现在能退吗”，模型没有识别这已经是需要订单状态的个案问题。
更稳的做法是先把问题分成三类。第一类是公共资料问答，只需要检索知识库并带出处回答。第二类是个案判断，需要读取用户订单、报名时间、课程状态，再结合规则说明可选方案。第三类是动作请求，例如申请退费、改课、转人工，这类请求必须调用工具，并在执行前让用户确认。分类不一定要用硬规则，可以让模型基于上下文做意图识别，但后端要把每类任务对应的工具和权限限制好。
上下文可以这样组织：系统边界说明它是培训服务助手；用户当前问题放在任务段；检索材料只放最新版本课程和规则；订单查询结果放在工具结果段；输出要求说明必须给出依据、不能承诺未执行动作、需要办理时给出下一步。这样模型回答“根据你报名的课程和当前退费规则，你还在可申请期内；我可以帮你生成申请草稿，提交前需要你确认”，就比直接说“可以退费”安全得多。
验收时不要只看回答顺不顺。应该准备样本：旧规则和新规则冲突时是否引用新规则；不同校区课程是否混淆；没有订单时是否追问；用户要求立即退款时是否走确认；知识库没有答案时是否承认缺失；引用链接是否能打开到对应条款。这个案例说明，上下文工程不是把材料堆给模型，而是把资料、身份、工具和动作边界组织成一条可检查链路。
上线前工程检查
上线一个入门级智能体前，可以按下面清单逐项检查。
输入侧：系统指令是否短而明确；用户输入和外部文档是否分区；是否为输出预留足够 Token；历史记录是否做了摘要；检索片段是否去重；工具结果是否限制长度。
知识侧：文档是否保留标题、章节、页码和版本；切块是否按语义而不是机械长度；向量检索是否带权限过滤；答案中的关键事实是否能对应引用；旧文档更新后旧向量是否失效。
工具侧：只读工具和写工具是否分级；工具参数是否有 schema；危险参数是否被后端拦截；写操作是否有用户确认；工具失败是否返回可理解状态；每次执行是否有审计记录。
体验侧：用户能否看见答案来源；模型不知道时是否清楚说明；需要补充信息时是否只问必要问题；错误提示是否面向最终用户；界面是否避免暴露内部字段、调试信息和模型原始 JSON。
评测侧：是否有固定样本；是否覆盖长上下文、冲突材料、权限拒绝、工具失败和提示注入；模型或提示词升级后是否重新评测；线上反馈是否能回流到样本集。
这份清单不复杂，但能挡住很多早期问题。只要每一项都有明确答案，应用就已经从“能聊天”走向“能交付”。
参考资料
- OpenAI Platform Docs：Text generation - 说明文本生成、消息输入和模型交互的基本方式。
- OpenAI Platform Docs：Function calling - 介绍工具调用、结构化参数和函数执行模式。
- OpenAI Platform Docs：Structured Outputs - 介绍使用 schema 约束模型输出的官方方法。
- OpenAI Platform Docs：Embeddings - 说明嵌入模型、语义检索和向量表示的基础概念。
- OpenAI Agents SDK Documentation - 介绍 Agent、工具、交接和追踪等智能体运行时能力。
- Anthropic Docs：Prompt engineering overview - 介绍 Claude 提示词设计和上下文组织建议。
- Anthropic Docs：Tool use - 说明模型使用外部工具的设计方式。
- Model Context Protocol Specification - 定义模型上下文协议中的工具、资源、提示和安全边界。
- Hugging Face NLP Course：Tokenizers - 讲解分词器、子词切分和 Token 表示。
- Hugging Face Transformers Documentation - 提供 Transformers 模型、分词器和推理生态文档。
- llama.cpp GitHub Repository - 本地推理、GGUF、量化和服务端运行的重要项目文档。
- Ollama Documentation - 本地模型运行、API、嵌入和工具调用相关文档。
- vLLM Documentation - 高吞吐推理、OpenAI 兼容服务和 PagedAttention 相关文档。
- Qdrant Documentation - 向量数据库、过滤、混合检索和相似度搜索资料。
- pgvector GitHub Repository - PostgreSQL 向量检索扩展，包含索引和相似度查询说明。
- OWASP Top 10 for LLM Applications 2025 - 总结提示注入、敏感信息泄露、工具滥用等 LLM 应用风险。
- NIST AI Risk Management Framework Generative AI Profile - 面向生成式 AI 风险治理的官方框架资料。
- Attention Is All You Need - Transformer 架构基础论文。
- Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks - RAG 方法代表论文。
- ReAct: Synergizing Reasoning and Acting in Language Models - 结合推理和行动的智能体方法论文。