AI Agent 入门 · 基础知识笔记

一份从「网络底层」到「API 调用」到「RAG / Agent」的完整入门笔记。

按学习逻辑顺序组织，适合长期保存与复习。

核心标准：看得懂、分得清——不求手写实现，但要能判断、能定位。

目录

• 网络底层：一次请求的旅程
• HTTP 报文：那坨文本长什么样
• API 调用基础：四件套
• 读懂 curl 命令
• 读懂 API 文档：五步套路
• 两类常见 API 对比
• Agent 开发者基础知识地图
• RAG：让模型用上你的私有数据
• RAG 进阶：把「能跑」变成「好用」
• 提示工程与 Agent 核心机制
• 上线与安全
• 总速记

一、网络底层：一次请求的旅程

你敲下网址按回车，到看见页面——中间那「嗖一下」其实有四步。看懂它，所有 API 调用都不再是黑箱。

核心比喻：寄一封挂号信。 先查到收件人门牌，由可靠运输公司送达，信封上锁谁也拆不开，对方收到后回你一封。

四步链路

关键概念澄清

DNS：把名字翻译成 IP 地址（数字门牌，如 142.x.x.x）。不是翻译成「网址」——网址是你敲的那个名字本身，IP 是翻译的结果。

IP 地址：那串数字门牌本身，机器之间靠它互相找。

TCP 的「可靠」具体指三件事：

• 签收确认：每段数据送到，对方回一个「收到」回执
• 丢了重发：没收到回执 = 知道丢了 → 自动重发，直到确认
• 排序：大数据切成小块分别送，到了按编号拼回正确顺序

一句话：TCP 可靠 = 不丢（丢了重发）+ 不乱（到了排序）+ 确认送达（每段回执）。

为什么调 API 用 TCP 不用 UDP：prompt 丢一个字、乱一个序模型就理解错了，所以要「不丢不乱」的 TCP。视频通话才用 UDP（快比全重要，丢一两帧无所谓）。

HTTP vs HTTPS：

• HTTP（无 S）= 明信片，数据明文，路上每一个经手者（WiFi 提供方、运营商、中间服务器）都能看到内容
• HTTPS（有 S）= 密封信，数据加密成乱码，只有收件人能解开
• 加密不是自动的，是 HTTPS 这个 S 带来的。所有正经 API 地址都是 https:// 开头，因为请求头里带着 API key，绝不能明文裸奔

这几个词的正确归位（容易混）：

• HTTP / HTTPS / MQTT → 最上层「应用怎么对话」，彼此平级（MQTT 多用于物联网设备）
• TCP / UDP → 中间层「怎么可靠运输」
• IP → 「找到哪台机器」
• MAC 地址 → 最底层「同一局域网内谁是谁」，平时不用碰

二、HTTP 报文：那坨文本长什么样

curl / Apifox 帮你拼好、真正发到网络上的原始样子：

POST /v1/chat/completions HTTP/1.1     ← 方法 + 地址（第一行）
Host: api.deepseek.com                 ┐
Authorization: Bearer sk-abc123        │ 说明信息（Headers）
Content-Type: application/json         │
Content-Length: 56                     ┘ ← 这行告诉服务器：正文有 56 字节
                                       ← 【空行】= 分界线！
{"model":"deepseek-v4-pro",...}        ← 正文（Body）

两个关键设计

空行：是 Headers 和 Body 之间的分界线。服务器从上往下逐行读，一遇到空行就知道「说明部分结束，下面全是正文」。像写信——抬头信息后空一行才是正文。

Content-Length：告诉服务器正文有多长（单位是字节，不是字符）。服务器读够这么多字节就知道 body 到此结束。

• 注意：一个中文字在 UTF-8 下占 3 个字节，不是 1 个。

空行 + Content-Length 是一对搭档：空行告诉服务器正文从哪开始，Content-Length 告诉它读到哪结束。

curl / Apifox 默默帮你做的事：写好第一行、把 -H 变成 Headers、自动数出 body 长度填 Content-Length、自动加分界空行。所以你用工具时从不操心这些。

三、API 调用基础：四件套

任何 API 调用，拆开都是同一副骨架。换接口只是换地址和换 JSON，骨架不变。

几个高频 Header

• Authorization：我是谁（Bearer ，Bearer 是固定认证方式关键字）
• Content-Type：我发的 body 是什么格式（application/json = JSON）。漏掉它很多 API 会拒收或报 400

状态码：办成没办成的回执

口诀：4xx 你错了，5xx 它崩了。 报错时先看响应 body 里的 error.message，比看状态码更精确。

JSON 写法规则

{ "model": "deepseek-v4-pro", "messages": [ { "role": "user", "content": "你好" } ] }

• {} 装键值对，[] 装列表
• key 和字符串都必须用双引号（不能用单引号）
• 最后一项后面不能有逗号（尾逗号是新手 80% 报错的原因）

四、读懂 curl 命令

curl https://你的网关/v1/images/generations \
  -H "Authorization: Bearer 你的key" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gpt-image-2", "prompt": "一只巡检机器人" }'

逐项拆解：

• curl：命令行发 HTTP 请求的工具。默认发 GET，一旦加 -d 就自动变 POST
• URL：https://（加密协议）+ 域名 + 路径（/v1 是版本号，后面是具体能力）
• 行尾 \：表示「这行没写完，下一行继续」，纯为换行好看。后面不能有空格
• -H：加一个请求头（header）
• -d：请求体（data）。外层用单引号包，因为 JSON 内部已用双引号。内容带单引号时用 -d @body.json 从文件读更省心

五、读懂 API 文档：五步套路

拿到任何 API 文档，按这个固定顺序看，永远不乱：

• URL 和方法 → 这是个什么能力（三秒扫顶部）
• 鉴权 / Authentication → 怎么证明身份（一般是 Bearer token）
• Request Body 参数表（最该花时间）：

- 先找 required 列表 → 哪些必填

- 再过每个字段的 enum（限定值）和 description（取值范围）

- 特别留意「仅支持 X 模型」这类条件限制（最容易踩的坑）

• Response 示例 → 返回什么结构，代码怎么解析（注意文档可能有的不一致）
• 错误码 → 报错时对照排查，优先看 body 的 error.message

读文档遇到「枚举 + description 补充」时，永远以 description 为准，enum 只是常用预设。

六、两类常见 API 对比（图像 vs 聊天）

图像 API 要点（以 gpt-image 系列为例）

• size：常用 1024x1024（方）/ 1536x1024（横）/ 1024x1536（竖）。约束：边长 ≤ 3840、必须是 16 的倍数、长短边比 ≤ 3:1
• quality：low（草稿，最快最省）→ 调好 prompt 再切 high（终稿）
• output_format：png（默认）/ jpeg / webp（存网站推荐 webp，省流量）
• response_format：GPT image 系列永远返回 base64，传 url 也无效（只对 dall-e 有效）
• 实操：试 prompt 阶段 quality=low + n=4 一次出多张挑，定稿再 high + n=1

聊天 API 要点

• messages 数组：每条 {"role": "...", "content": "..."}。role 三选一：

- system：设定人设和规则，开头放一条

- user：用户的话

- assistant：模型之前的回复

• role 是固定协议枚举，不是人设——人设写在 content 里
• 无状态真相：模型「记得」上文，纯粹因为你每次把全部历史又发了一遍
• 多轮对话：每轮要把上一轮的「问 + 答」都 append 进 messages 再发
• 关键返回字段：

- choices[0].message.content（99% 要的回复）

- finish_reason：stop 正常结束 / length 被 max_tokens 截断 / tool_calls 要调工具

- usage：本次花的 token（直接对应成本）

七、Agent 开发者基础知识地图

按「跟主线相关度」分三梯队，深度只需「看得懂、分得清」。

梯队一 · 紧挨 API，马上会撞到

梯队二 · 架构判断必备

梯队三 · 工程素养，慢慢渗透

只挑三个立刻补：① .env 密钥管理 → ② 数据库三分类 → ③ Webhook。

暂时别碰（超出基础边界）：Docker/容器、OAuth 完整流程、并发多线程、网络底层 TCP/DNS 握手细节。

八、RAG：让模型用上你的私有数据

核心问题：LLM 是 stateless 的，知识截止在训练那刻——它不知道你公司的事，也记不住太多（上下文窗口有限）。

RAG 精髓一句话：回答前，先去你的资料库里捞出最相关的几段，塞进 prompt，再让模型基于这几段回答。

核心比喻：给模型开一场开卷考试。 答题前先翻到相关那几页（检索）→ 摊在桌上（增强）→ 照着资料作答（生成）。

R = Retrieval（检索）  去向量库捞相关段落
A = Augmented（增强）  把资料拼进 prompt
G = Generation（生成） 发给 LLM 基于资料作答

两阶段流水线

阶段一 · 入库（离线，事先做一次）

你的文档 → Chunking 切小段 → 每段 Embedding 转向量 → 存进向量数据库

阶段二 · 问答（在线，每次提问时）

用户问题 → 同一个 Embedding 转向量 → 检索 R 找最近几段
        → 增强 A 拼进 prompt → 生成 G 发给 LLM

关键概念

• Embedding（向量化）：把文字转成坐标，让语义近的文字坐标也近。解决了「关键词搜不到同义不同字」的问题（「报销」能匹配「费用核销」）
• 向量数据库：专门存向量、并能秒找最近邻（Pinecone / Milvus / 轻量的 Chroma）。就是数据库三分类里的向量型
• Chunking（分块）：长文档切小段再转向量，检索才精准

两个新手必踩的坑

• 切块大小是手艺：切太大不精准，切太小丢上下文
• 两阶段必须用同一个 Embedding 模型：否则两张「语义地图」坐标系不同，算距离全乱

RAG vs 微调：选型判断

口诀：让模型「知道事实」用 RAG；让模型「改变行为风格」才考虑微调。九成企业问答场景 RAG 是正解。

重要认知：RAG 里真正调 LLM 的只有最后一步 G，前面切块/向量化/检索/拼 prompt 全是工程活——印证「agent 开发大部分是非 LLM 代码」。

九、RAG 进阶：把「能跑」变成「好用」

先承认：照基础流水线搭出的朴素 RAG（Naive RAG）经常答得烂——答非所问、漏关键、瞎编。这是固有缺陷，不是你搭错。毛病集中在三个环节。

环节一 · 切得对不对（Chunking）

• 按语义边界切：别固定每 500 字硬切（会把一句话/一张表劈开），按段落、标题层级、「第 X 条」这种完整单元切
• 重叠切分（Overlap）：相邻两块各留 ~50 字重复，避免关键信息卡在切口丢失

环节二 · 找得准不准（检索，翻车重灾区）

• 混合检索（Hybrid Search）：纯语义检索对精确编号/专有名词不灵（如「SKU-7782」会漏）。解法是语义路 + 关键词路两路合并。企业数据（全是编号）必上
• 重排序（Rerank）：捞回的 20 段良莠不齐，用更精细的小模型重打分，只留最相关 3-5 段。粗筛快 + 精排准
• 查询改写（Query Rewriting）：用户口语省略（「那上一条呢？」）没法直接检索，先让 LLM 补全成完整查询。多轮对话必备

环节三 · 答得实不实（生成）

• 强约束 Prompt：防幻觉——「只根据提供的资料回答，没有就说不知道，绝不编」
• 引用溯源（Citation）：答案里标出处（来自哪份文档哪一段），建立信任

Agentic RAG（进阶形态）

朴素 RAG 是「检索一次 → 答一次」死板；Agentic RAG 让 LLM 自己决策：要不要检索、查哪个库、没查够要不要再来一轮、要不要拆子问题。

这就是 agent 思想注入 RAG。企业管理 agent 的最终形态大概率就是它——自己决定该查钉钉记录、查数据库、还是查制度文档。

十、提示工程与 Agent 核心机制

提示工程

• role：固定协议枚举（system/user/assistant），标记「谁说的」。人设写在 content 里
• system 提示：上班第一句话——你是谁、按什么规矩干活
• temperature：创意旋钮。低（接近 0）稳定确定（编码用）；高（1+）发散有创意（文案用）
• 逼出 JSON：prompt 里明确要求 JSON 并给格式示例（光开 JSON 模式不说明，模型可能一直吐空白到卡死）
• 思维链（CoT）：让模型「一步步思考」，复杂推理出错更少
• 清晰具体 > 模糊：「写一篇 200 字、给小学生、语气温暖的猫科普」远好于「写点关于猫的东西」

Agent 核心机制

• Function Calling（工具调用）：模型不会自己执行代码，它只输出结构化的「我想调 XX 工具、参数 YY」，由你的代码接住并真正执行，再把结果喂回去
• ReAct 循环：推理(Reason) → 行动(Act) → 观察结果 → 再推理，循环往复直到完成。agent 能自主干活的核心
• tool 角色：工具执行结果用专门的 tool/function 角色消息追加回 messages，模型读到才能继续
• 记忆的本质：LLM 无状态，所谓记忆都是每次把该记的信息重新拼进上下文。短期=带历史，长期=向量库(RAG)
• 谁决定下一步：由 LLM 根据当前状态自主决策——这是 agent 区别于普通脚本的关键

核心认知：agent 开发大部分是非 LLM 代码。主体是写工具集成（调钉钉/跑测试/连库），真正调 LLM 只占一小部分。

十一、上线与安全

• .env：存密钥配置，代码用变量名引用，必须加进 .gitignore（忘了把 key 推上 GitHub 是经典事故）
• 前后端安全分界：前端代码跑在用户浏览器、源码可见 → 密钥绝不能放前端，只能在服务端
• 限流重试：高频调 API 遇 429，要降频 + 退避重试（等待逐次加长），不能硬刚
• 错误容错：网络请求注定有失败（超时/429/500），用 try/except 兜住、判断状态码、失败有降级，不能一错就崩
• 静态站部署：纯静态站用 Vercel / Cloudflare Pages，免费、一键、自带 HTTPS
• Webhook：连钉钉/飞书接收主动推来的消息——你给个回调地址，对方有事件主动 POST 过来，比轮询高效

十二、总速记

网络底层一条链

敲网址 → DNS 查门牌(IP) → TCP 可靠送(丢了重发) → HTTPS 上锁 → HTTP 对话

API 调用骨架

URL 选能力 → Header 给身份和格式 → Body 写参数 → 状态码看回执

4xx 你错了，5xx 它崩了

RAG 公式

RAG = Embedding(文字→坐标) + 向量库(存坐标·找最近) + Chunking(切小段) + 聊天接口(拼资料·生成)

知道事实用 RAG，改变风格才微调

Agent 一句话

模型负责「想」，你的工具代码负责「做」，做完喂回结果再想下一步（ReAct）

agent 开发大部分是非 LLM 的工程代码

不变的真相

LLM 是无状态的——每次调用都要重发完整历史，所有「记忆」都建立在这之上

*笔记完 · 标准：看得懂、分得清。下一步是动手——纸面到此够用，剩下靠手感。*