Starflyer

Agent 应用开发技术学习笔记

Thu, 03 Sep 2026 00:00:00 GMT

Agent 应用开发技术学习笔记

整理日期：2026-09-03
主题：Agent SDK、编排框架、RAG、Harness、低代码平台与生产配套设施

1. 先建立整体认识

Agent 应用不是“选一个框架就完成了”，而是由多个技术层共同组成。不同产品即使界面相似，解决的问题也可能完全不同。

用户界面 / API / 消息渠道
           ↓
AI 应用平台：Dify、Flowise、Langflow
           ↓
Agent SDK 与编排：LangChain、LangGraph、PydanticAI、OpenAI Agents SDK
           ↓
Agent Harness：Pi、DeepSeek Harness、OpenHands
           ↓
工具与数据：MCP、RAG、数据库、搜索、企业系统
           ↓
可靠执行与观测：Temporal、Restate、LangSmith、Langfuse

这些层可以组合。例如：

n8n 监听邮件并获取附件
  → 调用 Dify 完成知识检索与内容分析
  → 调用 LangGraph 服务处理复杂审批状态
  → n8n 将结果写入 CRM 并发送通知

2. 六类核心技术

类型	主要解决的问题	代表技术
Agent SDK	用代码定义 Agent、工具、记忆和结构化输出	LangChain、PydanticAI、OpenAI Agents SDK
Agent 编排框架	管理状态、分支、循环、多 Agent 和人工审批	LangGraph、CrewAI、Google ADK、Microsoft Agent Framework
数据与 RAG 框架	让 Agent 检索、理解和处理文档及企业数据	LlamaIndex、Haystack
Agent Harness	为 Agent 提供完整、可持续执行的运行环境	Pi、DeepSeek Harness、OpenHands、OpenCode
可视化 AI 平台	低代码搭建、测试和发布 AI 应用	Dify、Flowise、Langflow
自动化集成平台	连接业务系统、触发器、Webhook 和消息渠道	n8n

另外还有两类生产配套设施：

配套类型	代表技术
可靠执行	Temporal、Restate、DBOS、Prefect
观测与评测	LangSmith、Langfuse、Phoenix、Braintrust、Logfire、W&B Weave

3. Agent SDK：提供编程零件

Agent SDK 通常提供：

模型统一接口；
Tool calling；
Agent loop；
Memory 和 Session；
结构化输入输出；
模型厂商适配。

3.1 LangChain

LangChain 生态大、连接器丰富，适合需要同时集成多种模型、工具、Retriever 和向量数据库的项目。它更接近组件与集成层；复杂、状态化的 Agent 通常配合 LangGraph。

3.2 PydanticAI

PydanticAI 强调 Python 类型安全、依赖注入、结构化输出和可测试性。适合已有 FastAPI/Pydantic 技术栈、希望保持代码清晰的后端团队。

3.3 OpenAI Agents SDK

OpenAI Agents SDK 提供 Agent、Runner、Tools、Handoffs、Guardrails、Sessions 和 Tracing。适合主要使用 OpenAI 模型，希望用较少抽象快速构建工具型 Agent 的项目。

4. Agent 编排框架：控制执行过程

编排框架主要解决：

状态管理；
条件分支与循环；
任务拆解；
多 Agent 协作；
暂停、恢复与人工审批；
长流程中的错误处理。

4.1 LangGraph

LangGraph 将 Agent 表达成有状态图：Node 是模型、工具或普通代码，Edge 表示执行路径，State 保存共享状态，Checkpoint 用于中断与恢复。

它适合客服工单、研究报告、编码 Agent、审批流程，以及需要明确控制执行路径的长期任务。

LangChain：模型、Agent 和工具集成
LangGraph：状态、流程和执行控制
LangSmith：Tracing、评测与监控

三者属于同一生态，经常组合使用，并非三选一。

4.2 CrewAI

CrewAI 用 Agent、Task、Crew 和 Flow 表达角色式协作，适合研究、内容生产、市场分析等天然具有角色分工的任务。

多 Agent 并不天然优于单 Agent，它通常增加 Token、延迟、错误传播和评测难度。应先验证“单 Agent + 明确工作流”无法满足需求，再引入多 Agent。

4.3 Google ADK 与 Microsoft Agent Framework

Google ADK 适合 Gemini、Google Cloud、多语言 SDK 和多 Agent 场景。
Microsoft Agent Framework 适合 Azure、Microsoft 365、.NET 和企业身份体系。AutoGen 与 Semantic Kernel 的新项目应关注微软统一后的 Agent Framework 路线。

5. 数据与 RAG 框架：让 Agent 使用知识

5.1 LlamaIndex

LlamaIndex 擅长文档接入、解析、索引、检索、Query Engine、RAG 和数据型 Agent，适合企业知识库、研究助手和文档分析。

5.2 Haystack

Haystack 以 Document Store、Retriever、Component 和 Pipeline 为核心，适合企业搜索、文档问答和复杂检索流程。

简单选择：

文档、知识库和数据 Agent：优先比较 LlamaIndex 与 Haystack；
通用业务 Agent：优先比较 LangGraph、PydanticAI 与 OpenAI Agents SDK。

6. Agent Harness：给模型一个完整工作环境

Harness 可以理解为已经组装好的 Agent 运行外壳：

Agent Harness
├── 模型适配与 Agent loop
├── 上下文组装与压缩
├── Tool、文件系统与 Shell
├── 权限审批与沙箱
├── Session、持久化和失败恢复
├── Skills、Plugins 与 Subagents
├── 轨迹、回放和评测
└── CLI、TUI 或 Web UI

Agent SDK 提供零件；Harness 更接近一台可以直接工作的机器。Harness 与 LangGraph 也不互斥：前者提供环境，后者可以负责业务状态编排。

6.1 Pi Agent Harness

Pi 是 TypeScript monorepo，主要包含：

pi-ai：统一多模型 API；
pi-agent-core：Agent runtime、工具调用和状态管理；
pi-coding-agent：交互式编码 Agent；
pi-tui 与 pi-web-ui：终端和 Web UI；
Extensions 与 Skills 扩展机制。

Pi 核心相对精简，适合读源码、开发自己的 Coding Agent，或者将 Agent Core 嵌入 TypeScript 应用。

6.2 DeepSeek Harness

DeepSeek Harness（dsh）采用“一切皆插件”的思路，模型、工具、Skills、Session、Sandbox、Storage、Loop、调度和 UI 均可由插件提供。

它的 append-only Session Event Log 支持 Resume、Fork、Replay、Search 和 Trajectory 检查。运行模式包括 Standard、Code、Minimal 和 Creator。

截至本文整理时，它仍处于 Developer Preview，基础 API 可能发生破坏性变化，适合技术预研和插件化运行时研究，不宜未经充分验证直接成为关键生产系统的唯一底座。

6.3 Pi 与 DeepSeek Harness 对比

维度	Pi	DeepSeek Harness
主要语言	TypeScript	TypeScript
核心风格	精简、可扩展的 Coding Agent	全插件化 Agent Runtime
扩展机制	Extensions、Skills	Cordis Plugins
Session 特色	Agent 状态与会话	事件日志、恢复、分叉与回放
学习用途	Agent loop、工具和 UI	插件内核、事件系统和运行时组合
当前风险	相对成熟，但仍需评估版本兼容	Developer Preview，API 变化风险高

选择建议：

快速开发自己的 Coding Agent：优先研究 Pi；
研究可组合 Agent Runtime：重点研究 DeepSeek Harness；
构建稳定的业务流程：优先考虑 LangGraph/PydanticAI 与可靠执行设施；
构建 Agent IDE 或开放扩展平台：Pi 和 DeepSeek Harness 都有较高参考价值。

7. 可视化 AI 平台

7.1 Dify

Dify 的主角是 AI 应用，围绕以下能力构建：

模型与 Prompt 管理；
Agent、Workflow 与 Chatflow；
知识库、文档解析、Embedding 和检索；
会话与上下文；
Web App 与 API 发布；
AI 调用日志和运营。

适合企业知识助手、客服机器人、文档问答、内容生成和 AI 产品 MVP。

7.2 Flowise 与 Langflow

Flowise 偏向 AgentFlow、多 Agent 和复杂节点编排；
Langflow 偏向 LangChain 组件、RAG 与 MCP 的可视化实验。

低代码平台适合快速验证，但核心业务规则过多时，可视化画布会变得难以测试、Code Review 和版本管理。重要逻辑应逐步下沉到独立代码服务。

8. n8n：自动化与系统集成平台

n8n 虽然也有模型和 Agent 节点，但核心优势是：

Cron、Webhook 和事件触发；
HTTP API 与 OAuth 凭证；
邮件、IM、CRM、表格和数据库连接器；
JSON 转换、循环与批处理；
错误分支、重试、等待和通知。

它适合将 Agent 接入真实业务系统。例如：

收到客户投诉邮件
  → 下载附件
  → 查询 CRM
  → 调用 Agent 分类
  → 创建工单
  → 高风险投诉通知主管
  → 更新客户状态

9. n8n 与 Dify 的本质区别

二者都是低代码，但主角不同：

Dify 的主角是 AI 应用；n8n 的主角是业务自动化。

维度	Dify	n8n
产品定位	AI 应用开发平台	通用工作流自动化平台
核心对象	Prompt、模型、知识库、Agent、对话	Trigger、API、数据、SaaS、任务
最擅长	AI 助手、RAG、对话与内容生成	串联系统、数据同步、定时与事件自动化
AI 能力	原生核心能力	工作流中的一种能力
RAG	原生完整支持	通常需要组合外部组件
对话状态	原生支持	通常需要自己设计和存储
应用发布	Web App、聊天应用、API	Webhook、后台工作流和任务
外部连接器	有，但不是首要优势	核心优势
数据转换	中等	强
技术门槛方向	Prompt、模型、RAG、上下文	API、JSON、OAuth、数据库、错误处理

可以通过需求中的动词判断：

“问答、理解、检索、总结、生成、对话”多：倾向 Dify；
“定时、监听、同步、调用、批处理、通知、审批”多：倾向 n8n；
两组动词都多：组合使用 n8n 与 Dify；
涉及复杂状态和核心交易：增加独立代码服务或 LangGraph。

9.1 为什么会觉得 n8n 更技术

n8n 更接近“可视化后端代码”，使用者经常需要处理：

节点输入输出和 JSON 字段映射；
API 鉴权、分页与限流；
循环、批处理和数据转换；
超时、重试和失败分支；
外部数据库与系统状态。

Dify 隐藏了更多 AI 基础设施，但深入使用同样需要理解 Prompt 可靠性、文档切分、检索召回、上下文长度、幻觉和评测。

因此更准确的说法是：

n8n 的门槛偏传统软件工程，Dify 的门槛偏 AI 工程。

9.2 推荐组合方式

用户 / 定时器 / Webhook
          ↓
         n8n
   获取并整理业务数据
          ↓
      调用 Dify API
   RAG、推理、生成结果
          ↓
         n8n
审批、入库、通知、更新系统

10. 生产系统不可忽视的配套技术

10.1 协议与工具接口

MCP：连接 Agent 与工具、数据源；
A2A：用于 Agent 之间的发现和通信；
OpenAPI / JSON Schema：定义传统服务与 Tool 接口；
AG-UI：处理 Agent 与前端之间的事件交互。

新项目应优先设计清晰、强约束的 Tool Schema。有跨客户端复用需求时，再将工具封装为 MCP Server。

10.2 可靠执行

Temporal、Restate、DBOS 和 Prefect 可用于解决：

超时和自动重试；
断点恢复；
长时间等待人工审批；
幂等性和外部副作用；
工作流版本升级。

转账、下单、发消息和修改生产数据等工具必须设计幂等键、权限校验和操作日志。

10.3 可观测与评测

常见产品包括 LangSmith、Langfuse、Phoenix、Braintrust、Logfire 和 W&B Weave。至少需要记录：

每次模型调用和工具调用；
Prompt、模型版本和参数；
Token、成本与延迟；
最终状态和失败原因；
用户反馈与离线评测结果；
工具调用正确率和任务完成率。

没有评测集时，频繁修改 Prompt 很容易沦为凭感觉调参。

10.4 安全

Agent 能执行外部操作，因此应专门设计：

Prompt Injection 防护；
工具最小权限；
写操作人工审批；
容器或虚拟机沙箱；
密钥隔离和 PII 脱敏；
URL、文件访问边界；
调用次数和预算限制；
完整审计日志。

11. 按目标选型

目标	优先考虑
通用复杂业务 Agent	LangGraph
Python 强类型后端 Agent	PydanticAI
OpenAI 单一技术栈	OpenAI Agents SDK
企业知识库和文档 Agent	LlamaIndex / Haystack / Dify
快速交付 AI 产品 MVP	Dify
连接邮件、IM、CRM 和定时任务	n8n
角色式多 Agent	CrewAI，但先验证是否真的需要多 Agent
Google Cloud 与 Gemini	Google ADK
Azure、.NET 与 Microsoft 生态	Microsoft Agent Framework
自研 Coding Agent	Pi
插件化 Agent Runtime 预研	DeepSeek Harness
完整软件工程 Agent	OpenHands
TypeScript 全栈 Agent	Mastra 或 Pi Agent Core

常见组合：

通用生产 Agent：LangGraph + PostgreSQL + MCP + Langfuse/LangSmith
Python 轻量 Agent：PydanticAI + FastAPI + Logfire
快速 AI 产品：Dify + 企业知识库 + 独立业务 API
企业自动化：n8n + Dify/LangGraph 服务 + 企业系统
Coding Agent：Pi/OpenHands + 沙箱 + MCP + Session Store

12. 推荐学习顺序

不使用框架，理解一次基本的 Tool Calling Loop。
学习结构化输出、上下文管理和 Tool Schema。
掌握 MCP 的 Client、Server、Tool 和 Resource。
使用 PydanticAI 或 OpenAI Agents SDK 完成一个单 Agent。
使用 LangGraph 加入状态、分支、审批和断点恢复。
使用 Dify 完成一个可视化知识助手。
使用 n8n 接入 Webhook、邮件、IM 或定时任务。
阅读 Pi 或 DeepSeek Harness 源码，理解完整 Agent Runtime。
最后再研究 CrewAI 式多 Agent。
从项目早期建立 Trace 和小型评测集。

13. 最简记忆版

LangChain        = Agent 和工具的组件库
LangGraph        = 复杂 Agent 的状态与流程控制
LlamaIndex       = 数据、文档和 RAG
Pi / DSH         = 能实际持续工作的 Agent 运行外壳
Dify             = 低代码 AI 应用平台
n8n              = 低代码业务自动化与系统连接器
Temporal/Restate = 长任务的可靠执行
Langfuse         = Agent 的追踪、观测与评测

一句话总结：先按问题所在的技术层选工具。Dify 负责“把 AI 做成应用”，n8n 负责“让系统自动运转”，LangGraph 负责“让复杂 Agent 可控”，Pi 与 DeepSeek Harness 负责“给 Agent 一个完整工作环境”。

14. 延伸阅读

大模型本地部署学习笔记：参数量、权重精度与量化

Fri, 28 Aug 2026 00:00:00 GMT

大模型本地部署学习笔记：参数量、权重精度与量化

1. 参数量里的 7B、8B、27B 是什么？

B 是 Billion（十亿）。它表示模型拥有多少个可训练参数：

7B：约 70 亿个参数
8B：约 80 亿个参数
27B：约 270 亿个参数
70B：约 700 亿个参数

参数就是训练过程中被模型不断调整的数值。模型规模越大，潜在能力通常越强，但它也更占存储、内存/显存，推理速度可能更慢。

2. 参数、权重、偏置是什么关系？

神经网络的一层可简化表示为：

$$ f(x) = Wx + b $$

W：权重矩阵，内部包含大量权重值，例如 w_11、w_12。
b：偏置向量。
W 和 b 中所有能通过训练更新的数值，合起来就是这一层的参数。

因此，权重是参数的一大类；更广义地说，模型参数还可包括偏置、词嵌入、归一化层的可训练系数等。

例如，输入有 3 个数、输出有 2 个数时：

$$ W \in \mathbb{R}^{2 \times 3},\quad b \in \mathbb{R}^{2} $$

这一层共有 2 × 3 + 2 = 8 个参数。

3. 权重不等于参数精度

两者要区分：

权重：模型实际学到的数值，例如 0.12345678、-1.47。
参数精度 / 数据类型：用什么方式保存这些数值，例如 FP32、FP16、BF16 或 Q4。

可以把权重理解成照片内容，把精度或量化格式理解成照片是保存为原图、高清压缩图还是高压缩图。

4. FP32、FP16、BF16 是什么？

它们是浮点数格式，表示每个参数直接以多少个二进制位保存。

格式	每个参数约占用	常见用途
FP32	32 bit = 4 Byte	训练、需要较高数值精度的场景
FP16	16 bit = 2 Byte	GPU 推理、训练
BF16	16 bit = 2 Byte	深度学习训练与推理；数值范围更接近 FP32

Byte（字节）与 bit（比特）的关系是：8 bit = 1 Byte。本文的 GB 按十进制计算（1 GB = 10^9 Byte）；有些系统会用二进制单位 GiB（1 GiB = 2^30 Byte），所以显示数值会略小。

例如，8B 模型若全部按 FP16/BF16 保存，参数本身的理论体积为：

$$ 80\text{亿} \times 2\text{ Byte} \approx 16\text{ GB} $$

FP32 则约为 32 GB。

5. 什么是量化？

量化是把原本 FP16/BF16/FP32 中较精细的参数值，用更少的位数近似保存，从而减小模型文件和运行时内存占用。

例如原始权重是：

0.12345678

FP16 可能保存为接近 0.1235 的值；
Q4 量化通常不直接保存该小数，而是保存一个 4-bit 的近似编码，并结合缩放系数等信息，在推理时还原近似值。

量化不会减少模型的参数个数。8B 模型量化后仍是约 80 亿参数，只是每个参数的保存方式更省空间。

6. Q4_K_M、Q5_K_M、Q6_K、Q8_0 是什么？

这些是 GGUF / llama.cpp 生态中常见的具体量化格式，适用于 Ollama、LM Studio、llama.cpp 等本地运行工具。

名称	大意	取舍
Q4_K_M	名义 4-bit；K 系列实际平均约 4.5 bit/权重，中等质量配置	常见的效果、速度与体积平衡点
Q5_K_M	名义 5-bit；实际平均位宽通常约 5.5 bit/权重	比 Q4 更大，通常质量略更稳
Q6_K	名义 6-bit；实际平均位宽通常约 6.6 bit/权重	更接近原始权重，资源占用更高
Q8_0	平均约 8 bit/参数	质量保留通常更多，文件更大

其中：

Q4、Q5、Q6、Q8 表示大致的量化位宽；数字越大，通常模型越大、效果损失越少。
K 表示 llama.cpp/GGUF 的一类分块量化方法。
M 表示该 K 系列里的中等配置；它不是“参数量”的单位。

Q4_K_M 不意味着每个参数严格只占 4 bit。它需要分组缩放系数，且部分张量可能以不同精度保存；因此 K 系列 Q4 的实际平均位宽约 4.5 bit/权重（具体因模型而异）。

7. 为什么同一 8B 模型文件大小不同？

模型的参数量与量化精度是两个维度：

同一个 8B 模型：参数个数固定为约 80 亿
├─ FP32：约 32 GB（仅粗略计算参数本身）
├─ FP16 / BF16：约 16 GB
├─ Q8：约 8–10 GB
└─ Q4_K_M：约 5 GB 左右

以 8B 的 4-bit 为例：

$$ 80\text{亿}参数 \times 4\text{ bit} = 320\text{亿}\text{ bit} $$

再除以 8 bit/Byte：

$$ 320\text{亿} \div 8 = 40\text{亿}\text{ Byte} \approx 4\text{ GB} $$

上式是“严格每参数 4 bit”的理论下限。Q4_K_M 的有效平均位宽通常约 4.5 bit/权重，因此 8B 模型的量化权重本身就约 4.5 GB；再加部分高精度张量、词表和模型元数据后，文件可能约为 4.9 GB。

8. 开源模型通常发布哪些版本？

典型发布链路如下：

官方发布：FP16 / BF16 原始权重（Safetensors、Transformers 格式）
                  ↓
官方或社区转换：GGUF Q4/Q5/Q6/Q8、GPTQ、AWQ、EXL2 等量化版本

官方原始权重常用于微调、研究、服务器部署，体积较大。
FP32 很少单独作为推理模型发布，因为它比 FP16/BF16 大一倍，推理收益有限。
个人本地聊天通常下载量化版本，而不是原始 BF16/FP16 版本。

9. 参数量与本地电脑配置的关系

模型权重只是内存占用的一部分。下表是短上下文、单用户和特定运行时下的经验范围；实际运行还需为程序、上下文缓存（KV Cache）、系统和其他应用留余量。KV Cache 的大小还取决于模型架构、上下文长度、并发数和 KV 精度；多模态模型可能另有视觉组件占用。

模型规模（4-bit）	大致运行内存需求	常见建议
1.5B	2–3 GB	近年任意电脑基本可运行
7B / 8B	6–8 GB	16 GB 内存可用；8 GB 显存更舒适
14B	10–14 GB	32 GB 内存更合适；12–16 GB 显存较好
32B	22–28 GB	建议 32–64 GB 内存；24 GB 显存起步更理想
70B	45–55 GB	通常建议 64 GB 以上系统内存，或 48 GB 以上显存/多卡

CPU 推理：主要看系统内存，能运行但通常较慢。
NVIDIA GPU 推理：主要看显存，通常速度更快。要完整 GPU 卸载，模型权重、KV Cache 和运行时工作区都必须同时放入显存。
Apple Silicon Mac：CPU 与 GPU 共用统一内存，32 GB 或 64 GB 机型运行量化模型比较有优势。

系统内存足够但显存不足时，仍可使用 CPU 推理或 CPU/GPU 分层卸载，只是速度通常明显低于完整 GPU 卸载。

10. 实用选择建议

16 GB 内存或 8 GB 显存：优先选择 7B/8B 的 Q4_K_M。
32 GB 内存或 12–16 GB 显存：可考虑 14B 的 Q4/Q5，或 8B 的较高精度量化。
64 GB 内存或 24 GB 显存：32B 的 Q4 通常较合适。24 GB 显存通常无法将 70B 完整装入 GPU；若尝试 70B，往往需要 CPU/GPU 混合卸载或更低比特量化，且会受上下文长度影响。
在同一模型中：资源优先选 Q4_K_M；希望质量更稳选 Q5_K_M；资源充足且想保留更多质量可选 Q6/Q8。

11. 本次示例：Qwen3.8-27B

Qwen/Qwen3.8-27B 是图文多模态模型。它的官方仓库包含 Hugging Face Transformers 格式的原始权重，配置标记为 bfloat16（BF16）。它有约 270 亿参数，因此仅按参数粗略计算：

$$ 270\text{亿} \times 2\text{ Byte} \approx 54\text{ GB} $$

若用于普通个人电脑本地运行，通常应寻找其对应的 GGUF Q4/Q5 等量化版本；27B 的 Q4 主模型权重通常约在 16–18 GB 量级。实际包体和运行内存还可能包含视觉组件、投影器与上下文缓存，并要求运行时具备该多模态架构的支持。

12. 存储介绍：闪存、内存与显存

谈部署时常说“内存/显存够不够”，但存储其实是一个层级体系。按角色划分就是三大件：闪存（仓库）→ 内存（CPU 的工作台）→ 显存（GPU 的工作台），越往上速度越快、容量越小、每 GB 价格越贵。

硬盘/闪存 (数 TB, 慢, 断电保留)      ← 模型文件（GGUF）躺在这里
   ↓ 加载（秒级）
内存 (RAM, 16–64 GB, 快, 断电丢失)   ← CPU 推理时权重放这里
   ↓ 通过 PCIe 拷贝
显存 (VRAM, 8–24 GB, 极快)           ← GPU 推理时权重放这里
   ↓
GPU 计算核心

先纠正一个常见误区：存储不是“ROM（硬盘）+ RAM（内存）”两类。

ROM 的本义是只读存储器：断电保留数据、不可改写。
硬盘/SSD 同样断电保留数据，但可以随意读写，与“只读”的本义矛盾。
手机厂商“8GB RAM + 256GB ROM”是营销误用，那个“ROM”实际指的就是闪存。

下面逐一介绍这三类存储。

12.1 闪存：断电保留的“仓库”

闪存（Flash Memory）是一种可电擦写的非易失性芯片，是 ROM 家族的现代化后裔：保留断电不丢数据的特性，但通过“按块擦写”解决了不可写的问题。

传统 EEPROM 按字节擦写，电路面积大；
闪存按块擦写，密度高、便宜，但改一位也要重写整块。

SSD、U 盘、手机存储、SD 卡、Mac 的“硬盘”都是用闪存颗粒做成的产品，只是包装形态不同。

半导体存储芯片
├── RAM（易失，断电丢）
│   ├── 内存（DDR5）— CPU 工作台
│   └── 显存（GDDR、HBM）— GPU 工作台
└── ROM 家族（非易失，断电保留）
    ├── 早期真·只读 ROM（出厂烧死）
    ├── PROM / EPROM（可编程一次 / 紫外线擦除）
    └── EEPROM（可电擦写）→ 闪存（EEPROM 的块擦除版）

原理一瞥：闪存的基本单元是浮栅晶体管，电子被“打”进被绝缘层包裹的浮栅后困在里面，断电也跑不掉，电子多少决定读出 0 还是 1。绝缘层每次写入都会轻微损伤，因此每个单元的擦写次数有限（几千到十几万次），SSD 主控靠磨损均衡延长寿命。

	闪存	内存/显存（RAM）
断电	数据保留	数据丢失
写入速度	慢（毫秒级，且要整块擦）	极快（纳秒级，随写随改）
擦写寿命	有限	基本无限
每 GB 价格	便宜	贵好几倍

写入慢、寿命有限、不能按字节随意改——这三条决定了闪存当不了“工作台”，只能当“仓库”。

12.2 内存：CPU 的工作台

内存（RAM，即电脑上的内存条，DDR4/DDR5）是 CPU 的工作台：程序运行时代码和数据必须先加载到这里。它支持纳秒级随机读写，带宽约 50–90 GB/s，但断电即丢、每 GB 价格远高于闪存。本地部署时，CPU 推理的模型权重和 KV Cache 就放在内存里——这也是第 9 节表格里“运行内存需求”的由来。

12.3 显存：GPU 的工作台

显存（VRAM）本质上也是 RAM，只是服务对象从 CPU 换成 GPU。GPU 不直接用系统内存而要单独的显存，是因为带宽：大模型推理是海量矩阵乘法，GPU 每秒需要读取数百 GB 数据，内存的带宽喂不饱它。显存颗粒更贵、焊在 GPU 旁边，就是为了解决这个问题——这也是 CPU 推理慢的根本原因之一。

类型	典型带宽
DDR5 内存	约 50–90 GB/s
GDDR6X 显存（RTX 4090）	约 1000 GB/s
HBM3（数据中心 GPU）	3000+ GB/s

例外是 Apple Silicon Mac：M 系列芯片的 CPU 和 GPU 共享同一块统一内存，没有独立显存，所以 64 GB 内存的 Mac 能跑塞不进 24 GB 独立显卡的 32B 模型；代价是带宽（约 100–800 GB/s）仍低于独立显卡。

12.4 三者协作：本地部署的数据流

下载的 Q4_K_M 模型文件（约 5 GB）存在闪存上；启动推理时权重被加载进内存（CPU 推理）或显存（GPU 推理）；聊天产生的 KV Cache 也放在同一处。这解释了第 9 节的现象：文件只有 5 GB，运行却需要 6–8 GB 内存/显存——程序运行必须驻留在 RAM 类存储里，硬盘只是仓库，和游戏装在硬盘上、玩时加载进内存是同一个道理。

NVMe SSD 读取速度约 3–7 GB/s，对“加载一次模型”绰绰有余，但比显存带宽慢两三百倍，所以推理时权重不能边算边从 SSD 取。例外玩法：llama.cpp 可在内存不足时用 mmap 把 SSD 当溢出的权重仓库，速度极慢，但能让小内存机器跑大模型。

一句话总结

B 表示参数的数量；FP32、FP16、BF16 和 Q4 等表示这些参数保存得有多精细；参数越多或精度越高，模型文件与本地运行所需的内存/显存就越大。硬盘（闪存）是仓库，内存是 CPU 的工作台，显存是 GPU 的工作台。

从 0 到 1 搭建这个博客：选型与部署全记录

Thu, 27 Aug 2026 00:00:00 GMT

从 0 到 1 搭建这个博客：选型与部署全记录

本文是一篇完整的实战记录，分两部分：

第一部分：完整的选型分析（为什么是 Astro + Cloudflare Pages）

第二部分：从 0 到 1 的实际搭建与部署全过程（所有命令都在本机实测执行过）

全程由 Agent 在命令行完成，因此把每一步的命令和决策都原样记录，方便复现，也给自己留一份操作档案。

第一部分：选型 —— 为什么是 Astro + Cloudflare Pages

一、需求与约束

这次选型的核心目标不是单纯"把博客跑起来"，而是兼顾长期维护和服务器资源规划：

拥有独立域名和可迁移的博客内容
尽量少占用云服务器的常驻内存
云服务器后续还要部署其他网站
使用 Markdown 写作，并用 Git 管理内容
支持现代化样式、深色模式和一定的交互能力
不在第一版维护数据库、后台程序和复杂容器栈

在这些约束下，静态站点比 WordPress、Halo、Ghost 等动态 CMS 更合适。

二、静态站点到底"静态"在哪里

"静态"不是指页面不能动、不能搜索或不能评论，而是指：

访客访问页面时，托管平台直接返回提前生成好的 HTML、CSS 和 JavaScript 文件，不需要现场查询数据库并生成 HTML。

content/posts/hello.md
        ↓ Astro 构建
dist/posts/hello/index.html
        ↓ 访客访问
Cloudflare Pages 直接返回 index.html

页面仍可通过浏览器端 JavaScript 实现深色模式、搜索、图片灯箱、代码复制、动画、评论和阅读进度。

SSG、SSR、CSR 与 ISR

模式	全称	HTML 生成时机	运行时要求	典型场景
SSG	Static Site Generation	构建、发布时提前生成	否	Hugo、Hexo、Astro 静态模式
SSR	Server-Side Rendering	每次请求到达服务器时生成	需要服务端或边缘运行时	Next.js SSR、Astro Server 模式
CSR	Client-Side Rendering	浏览器下载 JavaScript 后生成	通常不需要渲染服务	React/Vue 单页应用
ISR	Incremental Static Regeneration	先生成，过期后按需更新	需要平台或运行时支持	内容量较大的现代网站

可以用做饭来类比：

SSG：客人来之前，饭已经做好
SSR：客人点单后，服务器现场做饭
CSR：服务器给食材，由客人的浏览器做饭

Astro 默认采用静态输出，因此本方案属于 SSG，而不是 SSR。

三、动态 CMS 与静态方案的初步筛选

方案	主要优点	主要代价	是否符合本次目标
Halo	中文后台、主题插件、Markdown/富文本编辑	Java 应用和数据库长期占用内存	一般
Ghost	写作体验好，支持会员与 Newsletter	Node.js、MySQL；使用邮件功能时还需 SMTP	一般
WordPress	插件和主题生态最大	PHP、数据库、插件安全更新较重	不优先
Hugo	构建极快、依赖少、长期稳定	中文主题和现代组件能力相对有限	符合
Hexo	中文博客生态强，Butterfly 等主题成熟	npm 依赖较多，构建速度不如 Hugo	符合
Astro	静态输出、现代组件化、扩展空间最大	相比传统博客生成器需要更多前端开发	最符合

如果目标是登录后台直接写文章，Halo 更方便；如果目标是低资源占用、Git 管理和长期可迁移，静态方案更有优势。

四、Hugo、Hexo 与 Astro 对比

维度	Hugo	Hexo	Astro
技术基础	Go	Node.js	Node.js / TypeScript
默认产物	静态 HTML	静态 HTML	静态 HTML
线上常驻内存	接近 0	接近 0	静态模式接近 0
构建速度	最快	中等	中等
博客开箱程度	高	很高	中等
中文主题生态	一般	很强	相对较少
UI 深度定制	Hugo 模板	主题、Pug、Stylus	组件化开发，能力最强
依赖复杂度	最低	中等	中等
适合人群	内容与稳定性优先	快速套成熟博客主题	现代化、个性化网站

1. Hugo

Hugo 通常以单个可执行文件运行，不依赖庞大的 node_modules，适合追求构建速度和长期稳定的人。

优点：构建速度快（文章很多时优势明显）；依赖链短，升级和安全风险较低；静态产物容易部署到任何 Web 服务器。
不足：中文主题和教程不如 Hexo 丰富；深度修改主题需要学习 Hugo 模板语法；现代前端组件和交互扩展不如 Astro 自然。

2. Hexo

Hexo 专门面向博客，中文生态成熟。

优点：分类、标签、归档、友链等博客功能成熟；Butterfly 等中文主题开箱即用；中文教程和社区资料丰富。
不足：npm 依赖和主题插件之间可能存在版本兼容问题；构建速度和依赖体积不如 Hugo；高度定制时容易进入主题"魔改"模式。

3. Astro

Astro 默认生成静态 HTML，也可以按需嵌入 React、Vue、Svelte 等交互组件。

优点：默认 SSG，不需要线上 Node.js 常驻进程；可以只给需要交互的部分发送 JavaScript；TypeScript、组件化和现代 CSS 工具支持好；后续可从博客扩展到个人主页、作品集或交互页面；构建后的 dist/ 可部署到 Pages，也可迁回自己的服务器。
不足：博客主题生态不如 Hexo；需要理解页面布局、内容集合和组件结构；如果以后切换到 SSR，需要额外的服务端、边缘或 Serverless 运行时；若部署在自有服务器，还会增加常驻内存开销。

4. 选择结论

极致稳定、构建最快：Hugo
想直接获得 Butterfly 风格：Hexo
希望兼顾静态博客和未来前端扩展：Astro

最终选择 Astro。原因不是它比 Hugo、Hexo 更省线上内存——三者静态部署后几乎相同——而是 Astro 在保持静态部署的同时提供了更大的界面和功能扩展空间。

五、云服务器、GitHub Pages 与 Cloudflare Pages

生成器和托管平台属于不同层次：

Hugo / Hexo / Astro：负责生成网站
云服务器 / GitHub Pages / Cloudflare Pages：负责托管网站

维度	自有云服务器	GitHub Pages	Cloudflare Pages
费用	已购买，但消耗资源和带宽	免费	免费额度足够个人博客
自定义域名	支持	支持	支持
HTTPS	自己配置 Caddy/Nginx	自动	自动
构建方式	本地或 CI 构建后上传	GitHub Actions	Git 集成自动构建
占用本机内存	静态托管增量很低	0	0
占用本机带宽	是	否	否
私有源码仓库	自己决定	免费账户的 Pages 能力受仓库类型限制	可连接私有 GitHub 仓库
预览部署	需要自己实现	可通过 Actions 实现	原生支持
动态扩展	可自由部署后端	基本没有	可接 Workers / Pages Functions

为什么选择 Cloudflare Pages

不消耗自己的 2C4G 服务器内存
不占用服务器有限的 5 Mbps 带宽
Git 推送后自动构建、发布
免费提供 HTTPS 和自定义域名
可以连接 GitHub 私有仓库
支持预览每次修改
静态产物标准化，随时可以迁回云服务器

六、域名、子域名与镜像

1. 一个域名可以创建多个子域名

不需要为主站和镜像分别购买两个域名。购买一个 example.com 后，可以创建：

子域名	用途	指向
`blog.example.com`	博客主站	Cloudflare Pages
`mirror.example.com`	博客镜像	GitHub Pages 或云服务器
`comment.example.com`	评论 API	自有云服务器
`www.example.com`	个人主页	任意平台

子域名通常不需要额外购买。

2. 什么是博客镜像

博客镜像是同一份静态构建产物部署到多个地址：

同一份 Git 仓库
        ↓ 构建
       dist/
        ├── Cloudflare Pages 主站
        ├── GitHub Pages 镜像
        └── 自有云服务器镜像

镜像主要用于故障备用、比较访问质量和避免单个平台不可用。它不是 Docker 镜像，也不等于完整灾备；Git 仓库和文章源码仍应额外备份。

七、最终架构：Astro + Cloudflare Pages

本地编写 Markdown / MDX
          ↓
提交到 GitHub 私有仓库
          ↓
Cloudflare Pages 检测到 push
          ↓
平台安装依赖并执行 npm run build
          ↓
Astro 将内容构建到 dist/
          ↓
Cloudflare 全球静态网络提供访问
          ↓
blog.example.com + 自动 HTTPS

Cloudflare Pages 基本构建配置：

Build command: npm run build
Build output directory: dist

Astro 保持默认静态模式：

import { defineConfig } from 'astro/config'

export default defineConfig({
  output: 'static'
})

不要使用 output: 'server'，除非未来确实需要请求时动态渲染，并愿意承担运行时服务和额外维护成本。

八、资源占用分析

1. 构建放在 Cloudflare 时

Astro 构建所需 CPU/内存：由 Cloudflare 承担
静态文件存储和流量：由 Cloudflare 承担
自己的云服务器内存：0
自己的云服务器带宽：0

这能把 2C4G 云服务器完整留给以后真正需要后端运行时和数据库的网站。

2. 如果以后迁回云服务器

只需将 dist/ 上传，通过一个共享的 Caddy 或 Nginx 进程托管多个目录：

Caddy/Nginx
├── blog.example.com   → /var/www/blog
├── site-a.example.com → /var/www/site-a
└── site-b.example.com → /var/www/site-b

多个静态站不需要分别启动多个 Node.js 服务，新增站点的常驻内存成本很低。

3. 容易被忽略的动态服务

功能方案	是否占用自有服务器
Giscus（GitHub Discussions）	否
Gitalk（GitHub Issues）	否
Artalk 自托管	是
Waline 自托管	是
Astro 本地静态搜索	否
Meilisearch 等独立搜索	是

为保持轻量，第一版可使用 Giscus 或暂时不加评论，搜索使用构建时索引或浏览器端本地搜索。

九、第一版功能边界

第一版实现：

Markdown/MDX 文章
首页、文章列表与文章详情
标签或分类
代码高亮与深色模式
RSS、Sitemap、SEO 和 Open Graph
响应式布局
Cloudflare Pages 自动部署
自定义域名与 HTTPS

后续再加：

Giscus 评论与全文搜索
图片灯箱和阅读进度
访问统计、友链、归档和作品集
Cloudflare R2 图片存储

暂不引入：

SSR、数据库和用户登录
自建管理后台
自建搜索集群
复杂微服务或容器编排

十、实施清单

项目初始化

[ ] 创建 Astro 项目
[ ] 确认 output: 'static'
[ ] 规划 src/content 文章集合
[ ] 选定基础主题或页面风格
[ ] 建立 Markdown Frontmatter 规范

博客基础能力

[ ] 首页、文章列表与文章详情
[ ] 代码高亮、标签、分类或归档
[ ] RSS、Sitemap 和 404 页面
[ ] SEO、Canonical URL、Open Graph
[ ] 深色模式与移动端适配

部署

[ ] 源码推送到 GitHub 私有仓库
[ ] Cloudflare Pages 连接仓库
[ ] 构建命令设为 npm run build
[ ] 输出目录设为 dist
[ ] 绑定自定义子域名
[ ] 验证 HTTPS、重定向和预览部署

运维与备份

[ ] 本地保留 Git 仓库副本
[ ] 定期同步到第二个备份位置
[ ] 图片压缩为 WebP/AVIF
[ ] 不存放大视频和大量原图
[ ] 固定 Node.js 与依赖版本
[ ] 定期检查构建日志和失效链接

第二部分：从 0 到 1 的实际搭建过程

以下是本机实际执行的全过程，所有命令都可复现。

一、环境准备

本机已有 Node.js 和 npm（Node v24.19.0 / npm 11.17.0），Git 已配好 SSH 密钥访问 GitHub，网络走本地 Clash 代理（127.0.0.1:7890 / 7891）。

node -v        # v24.19.0
npm  -v        # 11.17.0
ls ~/projects  # 工作目录

二、创建 Astro 项目

用 Astro 官方 blog 模板（自带文章集合、RSS、sitemap、深色模式）。

cd ~/projects
npm create astro@latest blog -- --template blog --install --no-git --yes

生成的目录结构（关键部分）：

blog/
├── astro.config.mjs          # 站点配置
├── package.json
├── src/
│   ├── content/blog/         # ▸ Markdown/MDX 文章存放处
│   ├── content.config.ts     # 内容集合 schema
│   ├── consts.ts             # 站点标题/描述
│   ├── layouts/BlogPost.astro
│   ├── pages/                # 首页、列表页、rss.xml.js
│   ├── styles/global.css
│   └── components/
└── public/                   # 静态资源

三、本地配置与定制

1. 确认静态模式（SSG）

在 astro.config.mjs 显式声明 output: 'static'：

export default defineConfig({
	site: 'https://example.com',   // 之后替换成真实域名
	output: 'static',              // SSG：构建时生成静态 HTML，不部署 Node 常驻进程
	integrations: [mdx(), sitemap()],
});

2. 站点元信息

在 src/consts.ts 里改为本站标题和描述：

export const SITE_TITLE = '肖飞的博客';
export const SITE_DESCRIPTION = '记录 AI 与开发学习笔记的个人博客。';

3. 内容集合加标签字段

在 src/content.config.ts 的 schema 里加可选 tags 数组：

pubDate: z.coerce.date(),
updatedDate: z.coerce.date().optional(),
tags: z.array(z.string()).optional(),
heroImage: z.optional(image()),

4. 列表页和文章页渲染标签

列表页 src/pages/blog/index.astro——每个文章卡片日期下方显示标签：

<p class="date">
	<FormattedDate date={post.data.pubDate} />
</p>
{post.data.tags && (
  <p class="tags">
    {post.data.tags.map((tag) => <span class="tag">#{tag}</span>)}
  </p>
)}

配套样式：

.tags { margin: 0.25rem 0 0; display: flex; gap: 0.5rem; flex-wrap: wrap; }
.tags .tag { font-size: 0.8rem; color: rgb(var(--gray)); background: rgba(var(--gray), 0.12); padding: 0.1rem 0.5rem; border-radius: 999px; }

文章页 src/layouts/BlogPost.astro——在标题下方同样显示标签（从 Props 解构 tags 即可）。

5. 给示例文章加标签

在 src/content/blog/first-post.md 的 frontmatter 里加上：

tags: ['astro', 'blog', '入门']

四、本地构建验证

cd ~/projects/blog
npm run build

输出在 dist/ 生成静态文件（首页、/blog/... 文章页、rss.xml、sitemap 等）：

✓ Completed in 1.14s
[@astrojs/sitemap] `sitemap-index.xml` created at `dist`
[build] 8 page(s) built in 2.29s

用 grep 验证标签已渲染进产物：

grep -o 'class="tags"' dist/blog/index.html
grep -o '#astro' dist/blog/index.html   # → 找到标签

五、git 初始化与提交

cd ~/projects/blog
git init -b main
git add -A
git commit -m "init: Astro blog (static SSG) - content collections, tags, rss/sitemap"

六、安装 gh CLI 并登录 GitHub

为了在命令行创建仓库和推送，安装 GitHub CLI（gh），并走 OAuth 设备码授权登录（headless 环境的标准方式）。

安装 gh（二进制，免 sudo）

cd /tmp
VER=$(curl -s https://api.github.com/repos/cli/cli/releases/latest | python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'].lstrip('v'))")
curl -sL -o gh.tgz "https://github.com/cli/cli/releases/download/v${VER}/gh_${VER}_linux_amd64.tar.gz"
tar xzf gh.tgz
mkdir -p ~/.local/bin
cp gh_${VER}_linux_amd64/bin/gh ~/.local/bin/
chmod +x ~/.local/bin/gh
export PATH="$HOME/.local/bin:$PATH"
gh --version   # gh version 2.98.0

设备码授权登录

调用 GitHub 的设备码接口拿到一次性代码，用户在浏览器打开 https://github.com/login/device 输入即可完成授权（授权范围：repo, read:org, gist）。授权成功后 gh 会把 token 写入 ~/.config/gh/hosts.yml：

gh auth status
# ✓ Logged in to github.com account Starflyr
#   Git operations protocol: ssh

💡 提示：这台机器之前配的 GitHub 账号是 Xiao198，后来改名为 Starflyr（显示名 Starflyer，与域名 starflyer.top 呼应），所以登录账号是 Starflyr。

七、创建私有仓库并推送

设置 git 提交身份与账号一致，然后一键创建私有仓库并推送：

git config --global user.name  "Starflyer"
git config --global user.email "Starflyr@users.noreply.github.com"

cd ~/projects/blog
gh repo create Starflyr/blog --private --source=. --remote=origin --push \
  --description "Personal blog built with Astro (static SSG)"

成功输出：

https://github.com/Starflyr/blog
To github.com:Starflyr/blog.git
 * [new branch]      HEAD -> main
branch 'main' set up to track 'origin/main'.

八、Cloudflare Pages 部署

登录 dash.cloudflare.com → Workers & Pages → Pages → Connect to Git
授权 Cloudflare 访问 GitHub，选择账号 Starflyr，选中仓库 blog
构建配置：

项值

Framework preset Astro

Build command npm run build

Build output directory dist
点 Save and Deploy，Cloudflare 自动拉取仓库、构建、发布

项	值
Framework preset	`Astro`
Build command	`npm run build`
Build output directory	`dist`

⚠️ 小坑：第一次很容易点进 Workers（会要求 npx wrangler deploy，那是跑服务端代码的），静态博客必须选 Pages。Pages 的构建界面不会出现 Deploy command: npx wrangler deploy 这一行，这是两个入口最明显的区分。

部署完成得到地址：https://blog-8jx.pages.dev/（blog 是项目名，8jx 是 Cloudflare 为全球唯一自动补的随机后缀）。

九、上线验证

# 关键页面 HTTP 状态
for u in "https://blog-8jx.pages.dev/" "https://blog-8jx.pages.dev/blog/first-post/" "https://blog-8jx.pages.dev/rss.xml"; do
  echo "$(curl -s -o /dev/null -w '%{http_code}' "$u")  $u"
done
# 全部 200

# 确认中文标题与编码
curl -s "https://blog-8jx.pages.dev/" | grep -io 'charset="?[a-z0-9-]*'
# charset=utf-8、title=肖飞的博客

# 确认标签渲染
curl -s "https://blog-8jx.pages.dev/blog/first-post/" | grep -o '#astro'
# → #astro

所有页面 HTTP 200，中文标题正常（utf-8），RSS / 标签 / 文章页全部跑通，博客正式上线。

十、后续规划

📝 写第一篇文章（就是这篇）
🏷 替换示例文章（first-post 等模板内容）
🌐 starflyer.top 域名审核通过后，绑定 blog.starflyer.top 子域名 + HTTPS
💬 加评论（Giscus）、全文搜索、访问统计
🖼 图片灯箱、阅读进度、归档、友链、作品集

总结

Astro 静态模式（SSG）
        +
GitHub 私有仓库（Starflyr/blog）
        +
Cloudflare Pages 自动构建与托管
        +
一个自定义域名（starflyer.top，待审核）

这个方案全程没有占用云服务器的内存和带宽；用 Markdown 写作 + Git 管理，便于备份和迁移；dist/ 标准化产物随时可以迁回自有服务器。

最重要的是这句：生成器决定怎么制作网站，托管平台决定网站在哪里运行。