@tom_doerr: 教授从头构建AI代理 https://github.com/pguso/ai-agents-from-scratch…

教学从基本原理构建AI代理 https://github.com/pguso/ai-agents-from-scratch… — # pguso/ai-agents-from-scratch 来源：https://github.com/pguso/ai-agents-from-scratch # 从头构建AI代理 学习在不使用框架的情况下本地构建AI代理。在使用生产框架之前，了解底层的工作原理。 代理架构概述 ## 目标 本仓库教你使用本地LLM和node-llama-cpp，从基本原理构建AI代理。通过这些示例，你将理解： - LLM在基本层面如何工作 - 代理到底是什么（LLM + 工具 + 模式） - 不同代理架构如何运作 - 框架为何做出某些设计选择 > 本教程的Python版本可在此处找到： > https://github.com/pguso/agents-from-scratch 理念：通过构建来学习。深入理解，然后明智地使用框架。 ## 配套网站 本仓库现在有一个配套网站：https://agentsfromscratch.com 该网站并非本仓库的替代品，而是一个概念性伴侣，用于： - 解释为什么每个示例存在 - 可视化从原始LLM调用到完整代理的学习路径 - 将代码、解释和核心概念分开 - 帮助你理解代理架构，然后使用框架 推荐工作流程： - 使用GitHub运行、修改和学习代码 - 使用网站获取心智模型、解释和进阶路径 > 将网站视为地图，本仓库视为地形。 ## 代理基础知识 - 从LLM到ReAct ### 先决条件 - Node.js 18+ - 至少8GB内存（推荐16GB） - 下载模型并放入./models/文件夹，详情见DOWNLOAD.md ### 安装 bash npm install ### 运行示例 bash node intro/intro.js node simple-agent/simple-agent.js node react-agent/react-agent.js ## 学习路径 按顺序学习以下示例，逐步构建理解： ### 1. 简介 - 基本LLM交互 intro/ | 代码 | 代码解释 | 概念 你将学到： - 加载和运行本地LLM - 基本的提示/响应循环 关键概念：模型加载、上下文、推理流水线、token生成 — ### 2. （可选）OpenAI简介 - 使用专有模型 openai-intro/ | 代码 | 代码解释 | 概念 你将学到： - 如何调用托管LLM（如GPT-4） - 温度控制 - Token使用情况 关键概念：推理端点、网络延迟、成本与控制、数据隐私、供应商依赖 — ### 3. 翻译 - 系统提示与专业化 translation/ | 代码 | 代码解释 | 概念 你将学到： - 使用系统提示来专业化代理 - 输出格式控制 - 基于角色的行为 - 针对不同模型的聊天封装 关键概念：系统提示、代理专业化、行为约束、提示工程 — ### 4. 思考 - 推理与问题解决 think/ | 代码 | 代码解释 | 概念 你将学到： - 配置LLM以进行逻辑推理 - 复杂的定量问题 - 纯LLM推理的局限性 - 何时使用外部工具 关键概念：推理代理、问题分解、认知任务、推理局限性 — ### 5. 批处理 - 并行处理 batch/ | 代码 | 代码解释 | 概念 你将学到： - 并发处理多个请求 - 用于并行的上下文序列 - GPU批处理 - 性能优化 关键概念：并行执行、序列、批大小、吞吐量优化 — ### 6. 编码 - 流式传输与响应控制 coding/ | 代码 | 代码解释 | 概念 你将学到： - 实时流式响应 - Token限制和预算管理 - 渐进式输出显示 - 用户体验优化 关键概念：流式传输、逐token生成、响应控制、实时反馈 — ### 7. 简单代理 - 函数调用（工具） simple-agent/ | 代码 | 代码解释 | 概念 你将学到： - 函数调用/工具使用基础 - 定义LLM可以使用的工具 - 参数的JSON Schema - LLM如何决定何时使用工具 关键概念：函数调用、工具定义、代理决策、执行行动 文本生成在这里变成了代理！ — ### 8. 带记忆的简单代理 - 持久状态 simple-agent-with-memory/ | 代码 | 代码解释 | 概念 你将学到： - 跨会话持久化信息 - 长期记忆管理 - 事实和偏好存储 - 记忆检索策略 关键概念：持久记忆、状态管理、记忆系统、上下文增强 — ### 9. ReAct代理 - 推理+行动 react-agent/ | 代码 | 代码解释 | 概念 你将学到： - ReAct模式（推理→行动→观察） - 迭代式问题解决 - 逐步工具使用 - 自我纠正循环 关键概念：ReAct模式、迭代推理、观察-行动循环、多步代理 这是现代代理框架的基础！ — ### 10. AoT代理 - 原子思考规划 aot-agent/ | 代码 | 代码解释 | 概念 你将学到： - 原子思考方法 - 多步计算的原子规划 - 操作之间的依赖管理 - 推理计划的结构化JSON输出 - 计划的确定性执行 关键概念：AoT规划、原子操作、依赖解析、计划验证、结构化推理 — ### 11. 错误处理 - LLM+工具的韧性 error-handling/ | 代码 | 代码解释 | 概念 你将学到： - 带稳定代码的类型化错误分类（验证、LLM、工具、工作流） - 超时、带退避/抖动的重试，以及瞬态失败分类 - LLM路径失败时的优雅降级（确定性工具回退） - 编排级错误（AgentWorkflowError）和用于支持的关联ID 关键概念：错误分类、重试策略、超时、回退、降级模式、可观察性、用户安全消息 — ### 12. 思维树 - 在推理分支上搜索 tree-of-thought/ | 代码 | 代码解释 | 概念 你将学到： - 从同一个部分计划生成多个候选下一步行动 - 使用代码中的确定性分数对分支进行排名和剪枝 - 运行一个紧凑的波束搜索循环，包含可检查的保留/剪枝决策 - 通过明确的健全性检查验证获胜路径 关键概念：思维树、波束搜索、分支剪枝、可验证目标、搜索控制器 — ### 13. 思维图 - 用于多源输出的DAG合并 graph-of-thought/ | 代码 | 代码解释 | 概念 你将学到： - 将推理建模为DAG：并行源提取→合并规则→最终草案 - 在生成前显式解决冲突（must_include、must_avoid、conflict_notes） - 添加确定性合并和草案合规性检查 - 并行运行独立节点以减少延迟 关键概念：思维图、DAG编排、多源融合、生成前合并、策略协调 决策指南：当需要搜索竞争路径时使用ToT；当需要将多个源合并为一个一致策略时使用GoT。比较两者请见： - ToT概念 - GoT概念 — ### 14. 思维链 - 可审计的逐步决策 chain-of-thought/ | 代码 | 代码解释 | 概念 你将学到： - 将高风险决策拆分为显式推理阶段 - 通过仅提取事实的步骤防止早期偏差 - 在应用策略之前平衡欺诈信号与合法性证据 - 生成可审计的最终决策，包含客户安全和内部输出 关键概念：思维链、结构化推理轨迹、策略约束决策、可解释性、可审查工作流 — ## 文档结构 每个示例文件夹包含： - .js - 可工作的代码示例 - CODE.md - 逐步代码解释 - 逐行分解 - 每个部分的作用 - 如何工作 - CONCEPT.md - 高层概念 - 对代理的重要性 - 架构模式 - 实际应用 - 简单图表 ## 核心概念 ### 什么是AI代理？ AI代理 = LLM + 系统提示 + 工具 + 记忆 + 推理模式 ─┬─ ──────┬────── ──┬── ──┬─── ────────┬──────── │ │ │ │ │ 大脑 身份 双手 状态 策略 ### 能力演进 1. intro → 基本LLM使用 2. translation → 专业化行为（系统提示） 3. think → 推理能力 4. batch → 并行处理 5. coding → 流式传输与控制 6. simple-agent → 工具使用（函数调用） 7. memory-agent → 持久状态 8. react-agent → 策略性推理+工具使用 ### 架构模式 简单代理（步骤1-5） 用户 → LLM → 响应 使用工具的代理（步骤6） 用户 → LLM ⟷ 工具 → 响应 记忆代理（步骤7） 用户 → LLM ⟷ 工具 → 响应 ↕ 记忆 ReAct代理（步骤8） 用户 → LLM → 思考 → 行动 → 观察 ↑ ↓ ↓ ↓ └──────┴──────┴──────┘ 迭代直到解决 ## ️ 辅助工具 ### PromptDebugger helper/prompt-debugger.js 用于调试发送给LLM的提示的工具。精确显示模型看到的内容，包括： - 系统提示 - 函数定义 - 对话历史 - 上下文状态 使用示例见simple-agent/simple-agent.js ## ️ 项目结构 - 基础 ai-agents/ ├── README.md ← 你在这里 ├─ examples/ ├── 01_intro/ │ ├── intro.js │ ├── CODE.md │ └── CONCEPT.md ├── 02_openai-intro/ │ ├── openai-intro.js │ ├── CODE.md │ └── CONCEPT.md ├── 03_translation/ │ ├── translation.js │ ├── CODE.md │ └── CONCEPT.md ├── 04_think/ │ ├── think.js │ ├── CODE.md │ └── CONCEPT.md ├── 05_batch/ │ ├── batch.js │ ├── CODE.md │ └── CONCEPT.md ├── 06_coding/ │ ├── coding.js │ ├── CODE.md │ └── CONCEPT.md ├── 07_simple-agent/ │ ├── simple-agent.js │ ├── CODE.md │ └── CONCEPT.md ├── 08_simple-agent-with-memory/ │ ├── simple-agent-with-memory.js │ ├── memory-manager.js │ ├── CODE.md │ └── CONCEPT.md ├── 09_react-agent/ │ ├── react-agent.js │ ├── CODE.md │ └── CONCEPT.md ├── 10_aot-agent/ │ ├── aot-agent.js │ ├── CODE.md │ └── CONCEPT.md ├── 11_error-handling/ │ ├── error-handling.js │ ├── CODE.md │ └── CONCEPT.md ├── 12_tree-of-thought/ │ ├── tree-of-thought.js │ ├── CODE.md │ └── CONCEPT.md ├── 13_graph-of-thought/ │ ├── graph-of-thought.js │ ├── CODE.md │ └── CONCEPT.md ├── 14_chain-of-thought/ │ ├── chain-of-thought.js │ ├── CODE.md │ └── CONCEPT.md ├── helper/ │ └── prompt-debugger.js ├── models/ ← 将你的GGUF模型放在这里 └── logs/ ← 调试输出 ## 其他资源 - node-llama-cpp：GitHub (https://github.com/withcatai/node-llama-cpp) - 模型中心：Hugging Face (https://huggingface.co/models?library=gguf) - GGUF格式：用于本地推理的量化模型 ## 贡献方式 这是一个学习资源。欢迎： - 对文档提出改进建议 - 添加更多示例模式 - 修复错误或不清楚的解释 - 分享你的成果！ ## 许可证 教育资源 - 可根据学习需要自由使用和修改。 — 用❤️为那些真正想理解AI代理的人而构建 从intro/开始，逐步深入。每个示例都建立在之前的基础上。同时阅读CODE.md和CONCEPT.md以获得全面理解。 祝学习愉快！