diff --git a/README.md b/README.md index ae25d87..093ceb0 100644 --- a/README.md +++ b/README.md @@ -1 +1,107 @@ -# Agent-Basic-Tutorial \ No newline at end of file +# Agent 基础教程 (Agent Basic Tutorial) + +欢迎来到 Agent 基础教程！本仓库旨在为开发者提供关于 AI Agent 使用的基础指导教程和实践经验分享。 + +## 📚 简介 + +AI Agent（智能代理）是一种能够自主感知环境、做出决策并执行任务的智能系统。本教程将帮助您从零开始学习和掌握 Agent 的开发与应用。 + +## 🎯 教程目标 + +- 理解 Agent 的核心概念和工作原理 +- 掌握 Agent 的基本开发方法 +- 学习 Agent 的实践应用场景 +- 了解 Agent 开发的最佳实践 +- 积累实际项目经验 + +## 📖 教程目录 + +### 基础教程 + +1. [**Agent 简介**](tutorials/01-introduction.md) + - 什么是 Agent + - Agent 的特点和优势 + - Agent 的应用场景 + +2. [**快速开始**](tutorials/02-getting-started.md) + - 环境准备 + - 第一个 Agent 程序 + - 基本操作示例 + +3. [**核心概念**](tutorials/03-core-concepts.md) + - Agent 架构 + - 感知与决策 + - 工具与能力 + - 记忆系统 + - 规划与执行 + +4. [**实践案例**](tutorials/04-practical-examples.md) + - 简单对话 Agent + - 任务执行 Agent + - 数据分析 Agent + - 代码生成 Agent + +5. [**最佳实践**](tutorials/05-best-practices.md) + - Prompt 工程技巧 + - Agent 设计原则 + - 性能优化方法 + - 错误处理策略 + +6. [**高级主题**](tutorials/06-advanced-topics.md) + - 多 Agent 协作 + - 长期记忆管理 + - Agent 安全性 + - 评估与测试 + +7. [**常见问题与故障排除**](tutorials/07-troubleshooting.md) + - 常见错误及解决方案 + - 调试技巧 + - 性能问题诊断 + +8. [**资源与参考**](tutorials/08-resources.md) + - 推荐工具和框架 + - 学习资源 + - 社区与支持 + +## 💡 代码示例 + +在 [examples](examples/) 目录中，您可以找到各种实用的代码示例： + +- 基础 Agent 实现 +- 工具集成示例 +- 实际应用场景演示 + +## 🚀 快速开始 + +1. 克隆本仓库： +```bash +git clone https://github.com/sunshuang1866/Agent-Basic-Tutorial.git +cd Agent-Basic-Tutorial +``` + +2. 从 [01-introduction.md](tutorials/01-introduction.md) 开始学习 + +3. 跟随教程逐步实践 + +4. 查看 [examples](examples/) 目录中的代码示例 + +## 🤝 贡献指南 + +欢迎贡献您的经验和案例！如果您有好的想法或发现问题： + +1. Fork 本仓库 +2. 创建您的特性分支 +3. 提交您的修改 +4. 发起 Pull Request + +## 📄 许可证 + +本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件 + +## 📧 联系方式 + +如有问题或建议，欢迎提 Issue 或联系维护者。 + +--- + +**Happy Learning! 祝学习愉快！** 🎉 \ No newline at end of file diff --git a/examples/01_simple_agent.py b/examples/01_simple_agent.py new file mode 100644 index 0000000..1ca95f3 --- /dev/null +++ b/examples/01_simple_agent.py @@ -0,0 +1,130 @@ +""" +简单 Agent 示例 + +这个示例展示了如何创建一个基本的 Agent，包含一个简单的时间查询工具。 + +学习要点： +1. Agent 的基本结构 +2. 如何定义工具 +3. 如何与 Agent 交互 +""" + +from langchain.agents import initialize_agent, AgentType +from langchain.chat_models import ChatOpenAI +from langchain.tools import Tool +from datetime import datetime +import os +from dotenv import load_dotenv + +# 加载环境变量 +load_dotenv() + +# 检查 API 密钥 +if not os.getenv('OPENAI_API_KEY'): + print("错误：未找到 OPENAI_API_KEY 环境变量") + print("请在 .env 文件中设置：OPENAI_API_KEY=your-api-key") + exit(1) + + +def get_current_time() -> str: + """ + 获取当前时间 + + Returns: + str: 格式化的当前时间字符串 + """ + now = datetime.now() + return now.strftime("%Y年%m月%d日 %H:%M:%S") + + +def get_current_date() -> str: + """ + 获取当前日期 + + Returns: + str: 格式化的当前日期字符串 + """ + now = datetime.now() + return now.strftime("%Y年%m月%d日 星期%w") + + +def main(): + """主函数""" + + print("=" * 50) + print("简单 Agent 示例") + print("=" * 50) + print() + + # 1. 初始化大语言模型 + print("正在初始化 Agent...") + llm = ChatOpenAI( + temperature=0, # 温度为0，使输出更确定 + model="gpt-3.5-turbo" + ) + + # 2. 定义工具列表 + tools = [ + Tool( + name="GetCurrentTime", + func=get_current_time, + description="获取当前的日期和时间。当用户询问现在几点或当前时间时使用此工具。" + ), + Tool( + name="GetCurrentDate", + func=get_current_date, + description="获取当前的日期和星期。当用户询问今天是几号或星期几时使用此工具。" + ), + ] + + # 3. 初始化 Agent + agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True, # 显示详细执行过程 + handle_parsing_errors=True # 处理解析错误 + ) + + # 4. 测试 Agent + test_queries = [ + "现在几点了？", + "今天是星期几？", + "告诉我现在的完整日期和时间", + ] + + for i, query in enumerate(test_queries, 1): + print(f"\n{'='*50}") + print(f"测试 {i}: {query}") + print(f"{'='*50}\n") + + try: + response = agent.run(query) + print(f"\n✅ 回答：{response}\n") + except Exception as e: + print(f"\n❌ 错误：{str(e)}\n") + + # 5. 交互模式 + print("\n" + "=" * 50) + print("进入交互模式（输入 'quit' 或 'exit' 退出）") + print("=" * 50 + "\n") + + while True: + user_input = input("您的问题：").strip() + + if user_input.lower() in ['quit', 'exit', '退出', 'q']: + print("\n再见！👋") + break + + if not user_input: + continue + + try: + response = agent.run(user_input) + print(f"\n回答：{response}\n") + except Exception as e: + print(f"\n错误：{str(e)}\n") + + +if __name__ == "__main__": + main() diff --git a/examples/02_chat_agent.py b/examples/02_chat_agent.py new file mode 100644 index 0000000..4074bea --- /dev/null +++ b/examples/02_chat_agent.py @@ -0,0 +1,160 @@ +""" +对话 Agent 示例 + +这个示例展示了如何创建一个支持多轮对话的 Agent，能够记住之前的对话内容。 + +学习要点： +1. 如何使用记忆系统 +2. 多轮对话的实现 +3. 对话上下文管理 +""" + +from langchain.agents import initialize_agent, AgentType +from langchain.chat_models import ChatOpenAI +from langchain.memory import ConversationBufferMemory +from langchain.tools import Tool +import os +from dotenv import load_dotenv + +# 加载环境变量 +load_dotenv() + + +def save_user_info(info: str) -> str: + """ + 保存用户信息（模拟） + + Args: + info: 用户信息 + + Returns: + str: 确认消息 + """ + # 实际应用中可以保存到数据库 + return f"已记录信息：{info}" + + +def calculate(expression: str) -> str: + """ + 执行数学计算 + + Args: + expression: 数学表达式 + + Returns: + str: 计算结果 + """ + try: + # 安全性注意：实际应用中应该使用更安全的计算方法 + result = eval(expression) + return f"计算结果：{result}" + except Exception as e: + return f"计算出错：{str(e)}" + + +def main(): + """主函数""" + + print("=" * 50) + print("对话 Agent 示例") + print("=" * 50) + print("这个 Agent 能够记住之前的对话内容") + print() + + # 1. 初始化 LLM + llm = ChatOpenAI( + temperature=0.7, # 稍高的温度使对话更自然 + model="gpt-3.5-turbo" + ) + + # 2. 创建记忆系统 + memory = ConversationBufferMemory( + memory_key="chat_history", + return_messages=True + ) + + # 3. 定义工具 + tools = [ + Tool( + name="SaveUserInfo", + func=save_user_info, + description="保存用户的个人信息，如姓名、爱好等。输入应该是要保存的信息文本。" + ), + Tool( + name="Calculate", + func=calculate, + description="执行数学计算。输入应该是数学表达式，如 '2+3' 或 '10*5'。" + ), + ] + + # 4. 初始化 Agent（使用支持对话的类型） + agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION, + memory=memory, + verbose=True, + handle_parsing_errors=True + ) + + # 5. 示例对话流程 + print("演示多轮对话能力：\n") + + conversations = [ + "你好！我叫张三。", + "我喜欢编程和阅读。", + "请帮我记住这些信息。", + "我叫什么名字？", + "我有什么爱好？", + ] + + for i, message in enumerate(conversations, 1): + print(f"\n{'='*50}") + print(f"对话 {i}") + print(f"{'='*50}") + print(f"用户：{message}\n") + + try: + response = agent.run(message) + print(f"Agent：{response}\n") + except Exception as e: + print(f"错误：{str(e)}\n") + + # 6. 交互模式 + print("\n" + "=" * 50) + print("进入交互模式") + print("提示：Agent 会记住你告诉它的信息") + print("输入 'quit' 退出") + print("=" * 50 + "\n") + + while True: + user_input = input("您：").strip() + + if user_input.lower() in ['quit', 'exit', '退出', 'q']: + print("\n再见！👋") + break + + if not user_input: + continue + + try: + response = agent.run(user_input) + print(f"Agent：{response}\n") + except Exception as e: + print(f"错误：{str(e)}\n") + + # 7. 显示对话历史 + print("\n" + "=" * 50) + print("对话历史：") + print("=" * 50) + + # 获取记忆内容 + memory_vars = memory.load_memory_variables({}) + if 'chat_history' in memory_vars: + for msg in memory_vars['chat_history']: + role = "用户" if hasattr(msg, 'type') and msg.type == 'human' else "Agent" + print(f"{role}：{msg.content}") + + +if __name__ == "__main__": + main() diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..4145de0 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,146 @@ +# Agent 示例代码 + +本目录包含各种 Agent 应用的示例代码。 + +## 📁 目录结构 + +``` +examples/ +├── README.md # 本文件 +├── 01_simple_agent.py # 简单 Agent 示例 +├── 02_chat_agent.py # 对话 Agent +├── 03_calculator_agent.py # 计算器 Agent +├── 04_file_manager_agent.py # 文件管理 Agent +├── 05_data_analysis_agent.py # 数据分析 Agent +└── requirements.txt # 依赖包列表 +``` + +## 🚀 快速开始 + +### 1. 安装依赖 + +```bash +cd examples +pip install -r requirements.txt +``` + +### 2. 配置 API 密钥 + +创建 `.env` 文件： + +```bash +OPENAI_API_KEY=your-api-key-here +``` + +### 3. 运行示例 + +```bash +# 简单 Agent +python 01_simple_agent.py + +# 对话 Agent +python 02_chat_agent.py + +# 其他示例... +``` + +## 📝 示例说明 + +### 01_simple_agent.py +**功能：** 基础 Agent 实现 +**学习点：** +- Agent 初始化 +- 工具定义 +- 基本交互 + +### 02_chat_agent.py +**功能：** 支持多轮对话的 Agent +**学习点：** +- 记忆系统 +- 对话上下文 +- 连贯交互 + +### 03_calculator_agent.py +**功能：** 数学计算 Agent +**学习点：** +- 工具集成 +- 错误处理 +- 结果验证 + +### 04_file_manager_agent.py +**功能：** 文件操作 Agent +**学习点：** +- 文件系统操作 +- 安全性考虑 +- 权限控制 + +### 05_data_analysis_agent.py +**功能：** 数据分析 Agent +**学习点：** +- 数据处理 +- 可视化 +- 报告生成 + +## 💡 使用建议 + +1. **从简单开始**：先运行 `01_simple_agent.py` 了解基础 +2. **逐步深入**：按顺序学习各个示例 +3. **动手修改**：尝试修改代码，观察效果 +4. **解决问题**：遇到问题参考 [故障排除](../tutorials/07-troubleshooting.md) + +## 🔧 自定义示例 + +可以基于这些示例创建自己的 Agent： + +```python +from langchain.agents import initialize_agent, AgentType +from langchain.chat_models import ChatOpenAI +from langchain.tools import Tool + +# 1. 初始化 LLM +llm = ChatOpenAI(temperature=0) + +# 2. 定义工具 +def my_custom_tool(input_str: str) -> str: + # 实现你的逻辑 + return f"处理结果：{input_str}" + +tools = [ + Tool( + name="MyTool", + func=my_custom_tool, + description="工具描述" + ) +] + +# 3. 创建 Agent +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True +) + +# 4. 运行 +response = agent.run("你的问题") +print(response) +``` + +## 📚 相关资源 + +- [教程文档](../tutorials/) +- [最佳实践](../tutorials/05-best-practices.md) +- [常见问题](../tutorials/07-troubleshooting.md) + +## 🤝 贡献 + +欢迎贡献新的示例代码！请确保： + +- 代码清晰易懂 +- 包含注释说明 +- 提供使用说明 +- 测试通过 + +## 📄 许可证 + +本项目采用 MIT 许可证。详见 [LICENSE](../LICENSE) 文件。 diff --git a/examples/requirements.txt b/examples/requirements.txt new file mode 100644 index 0000000..2ec4de2 --- /dev/null +++ b/examples/requirements.txt @@ -0,0 +1,3 @@ +langchain>=0.1.0 +openai>=1.0.0 +python-dotenv>=1.0.0 diff --git a/tutorials/01-introduction.md b/tutorials/01-introduction.md new file mode 100644 index 0000000..eb19a77 --- /dev/null +++ b/tutorials/01-introduction.md @@ -0,0 +1,129 @@ +# Agent 简介 + +## 什么是 Agent？ + +Agent（智能代理）是一种能够感知环境、自主决策并执行任务的智能系统。在 AI 领域，Agent 通常指基于大语言模型（LLM）的智能代理，它能够理解自然语言指令，使用各种工具，并完成复杂的任务。 + +### Agent 的核心特征 + +1. **自主性（Autonomy）** + - 能够在没有持续人工干预的情况下独立运行 + - 可以自主决定采取什么行动 + +2. **感知能力（Perception）** + - 能够感知和理解环境信息 + - 可以接收和处理用户输入 + +3. **决策能力（Decision Making）** + - 基于感知到的信息做出判断 + - 选择最优的行动方案 + +4. **执行能力（Action）** + - 能够调用工具和 API + - 可以与外部系统交互 + +5. **学习能力（Learning）** + - 从经验中学习和改进 + - 适应新的情况和需求 + +## Agent 与传统程序的区别 + +| 特性 | 传统程序 | Agent | +|------|---------|-------| +| 控制方式 | 预定义流程 | 自主决策 | +| 灵活性 | 固定逻辑 | 动态适应 | +| 智能水平 | 基于规则 | 基于理解 | +| 交互方式 | 结构化输入 | 自然语言 | + +## Agent 的优势 + +1. **灵活性高**：能够处理多样化和不确定的任务 +2. **易用性强**：通过自然语言交互，降低使用门槛 +3. **自动化程度高**：可以完成复杂的多步骤任务 +4. **可扩展性好**：容易集成新的工具和能力 + +## Agent 的应用场景 + +### 1. 个人助理 +- 日程管理 +- 邮件处理 +- 信息查询 +- 任务提醒 + +### 2. 客户服务 +- 智能客服 +- 问题解答 +- 售后支持 +- 用户引导 + +### 3. 数据分析 +- 数据查询 +- 报表生成 +- 趋势分析 +- 可视化呈现 + +### 4. 内容创作 +- 文案撰写 +- 代码生成 +- 文档编写 +- 翻译校对 + +### 5. 自动化运维 +- 系统监控 +- 日志分析 +- 故障诊断 +- 自动修复 + +### 6. 研究辅助 +- 文献检索 +- 数据收集 +- 实验设计 +- 结果分析 + +## Agent 的工作流程 + +``` +用户输入 → 理解意图 → 规划任务 → 执行动作 → 观察结果 → 调整策略 → 返回结果 +``` + +### 典型的 Agent 工作周期 + +1. **接收任务**：理解用户的需求和目标 +2. **分析任务**：将复杂任务分解为子任务 +3. **规划方案**：确定执行步骤和所需工具 +4. **执行操作**：调用工具、获取信息、处理数据 +5. **评估结果**：检查执行结果是否满足预期 +6. **迭代优化**：如需要，调整策略并重新执行 +7. **总结反馈**：向用户报告结果 + +## Agent 的技术架构 + +### 核心组件 + +1. **大语言模型（LLM）**：Agent 的"大脑"，负责理解、推理和决策 +2. **工具集（Tools）**：Agent 的"手"，用于执行具体操作 +3. **记忆系统（Memory）**：Agent 的"记忆"，存储历史信息 +4. **规划器（Planner）**：Agent 的"思考"，制定执行计划 +5. **执行器（Executor）**：Agent 的"行动"，执行具体任务 + +### 常见的 Agent 框架 + +- **LangChain**：功能丰富的 Agent 开发框架 +- **AutoGPT**：自主 Agent 系统 +- **BabyAGI**：任务驱动的自主 Agent +- **AgentGPT**：Web 平台的 Agent 系统 +- **Semantic Kernel**：微软的 Agent 框架 + +## 下一步 + +现在您已经了解了 Agent 的基本概念，接下来可以： + +1. 阅读 [快速开始](02-getting-started.md) 来创建您的第一个 Agent +2. 深入学习 [核心概念](03-core-concepts.md) +3. 查看 [实践案例](04-practical-examples.md) 了解具体应用 + +## 推荐阅读 + +- [LangChain 官方文档](https://python.langchain.com/) +- [OpenAI Agent 指南](https://platform.openai.com/docs/guides/agents) +- [Agent 研究论文合集](https://github.com/Paitesanshi/LLM-Agent-Survey) diff --git a/tutorials/02-getting-started.md b/tutorials/02-getting-started.md new file mode 100644 index 0000000..ac9c1b5 --- /dev/null +++ b/tutorials/02-getting-started.md @@ -0,0 +1,259 @@ +# 快速开始 + +本教程将指导您创建第一个 Agent 程序，了解 Agent 开发的基本流程。 + +## 环境准备 + +### 1. 安装 Python + +确保您的系统已安装 Python 3.8 或更高版本： + +```bash +python --version +``` + +### 2. 创建虚拟环境 + +```bash +# 创建虚拟环境 +python -m venv agent-env + +# 激活虚拟环境 +# Windows +agent-env\Scripts\activate +# Linux/Mac +source agent-env/bin/activate +``` + +### 3. 安装依赖包 + +我们使用 LangChain 作为 Agent 开发框架： + +```bash +pip install langchain openai python-dotenv +``` + +### 4. 配置 API 密钥 + +创建 `.env` 文件，添加您的 OpenAI API 密钥： + +```bash +OPENAI_API_KEY=your-api-key-here +``` + +## 第一个 Agent 程序 + +### 示例 1：简单的对话 Agent + +创建 `simple_agent.py` 文件： + +```python +from langchain.agents import initialize_agent, AgentType +from langchain.chat_models import ChatOpenAI +from langchain.tools import Tool +import os +from dotenv import load_dotenv + +# 加载环境变量 +load_dotenv() + +# 初始化 LLM +llm = ChatOpenAI(temperature=0, model="gpt-3.5-turbo") + +# 定义一个简单的工具 +def get_current_time(): + """获取当前时间""" + from datetime import datetime + return datetime.now().strftime("%Y-%m-%d %H:%M:%S") + +# 创建工具列表 +tools = [ + Tool( + name="GetTime", + func=get_current_time, + description="获取当前系统时间" + ) +] + +# 初始化 Agent +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True +) + +# 运行 Agent +if __name__ == "__main__": + response = agent.run("现在几点了？") + print(f"\n回答：{response}") +``` + +运行程序： + +```bash +python simple_agent.py +``` + +### 示例 2：带计算功能的 Agent + +```python +from langchain.agents import initialize_agent, AgentType, load_tools +from langchain.chat_models import ChatOpenAI +from dotenv import load_dotenv + +load_dotenv() + +# 初始化 LLM +llm = ChatOpenAI(temperature=0) + +# 加载内置工具 +tools = load_tools(["python_repl"], llm=llm) + +# 初始化 Agent +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True +) + +# 测试计算功能 +if __name__ == "__main__": + # 简单计算 + result = agent.run("请计算 123 * 456 等于多少") + print(f"结果：{result}") + + # 复杂计算 + result = agent.run("请帮我计算斐波那契数列的第10项") + print(f"结果：{result}") +``` + +## 理解 Agent 的工作过程 + +当您运行上面的示例时，您会看到类似的输出： + +``` +> Entering new AgentExecutor chain... +我需要使用 GetTime 工具来获取当前时间 + +Action: GetTime +Action Input: 无需输入 + +Observation: 2024-01-15 14:30:25 +Thought: 我现在知道当前时间了 + +Final Answer: 现在是 2024年1月15日 14:30:25 + +> Finished chain. +``` + +这个过程展示了 Agent 的核心工作机制： + +1. **Thought（思考）**：Agent 分析问题，决定需要采取什么行动 +2. **Action（行动）**：选择合适的工具 +3. **Action Input（输入）**：为工具提供必要的输入 +4. **Observation（观察）**：获取工具执行的结果 +5. **Final Answer（最终答案）**：基于观察结果给出回答 + +## Agent 类型说明 + +LangChain 支持多种 Agent 类型： + +### 1. ZERO_SHOT_REACT_DESCRIPTION +- 最常用的 Agent 类型 +- 基于工具描述选择工具 +- 适合大多数场景 + +### 2. CONVERSATIONAL_REACT_DESCRIPTION +- 支持对话上下文 +- 能记住之前的对话内容 +- 适合需要多轮对话的场景 + +### 3. STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION +- 支持结构化输入 +- 适合复杂工具调用 +- 可以处理多参数工具 + +### 4. SELF_ASK_WITH_SEARCH +- 自我提问式 Agent +- 擅长分解复杂问题 +- 适合需要逐步推理的场景 + +## 常见问题 + +### Q1: API 调用失败怎么办？ + +确认： +- API 密钥是否正确 +- 网络连接是否正常 +- API 额度是否充足 + +### Q2: Agent 响应很慢？ + +可以： +- 使用更快的模型（如 gpt-3.5-turbo） +- 减少工具数量 +- 优化工具描述 + +### Q3: Agent 没有调用工具？ + +检查： +- 工具描述是否清晰 +- 问题是否真的需要该工具 +- 尝试使用 `verbose=True` 查看详细日志 + +## 调试技巧 + +### 1. 启用详细日志 + +```python +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True # 显示详细执行过程 +) +``` + +### 2. 设置最大迭代次数 + +```python +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + max_iterations=5 # 限制最大迭代次数 +) +``` + +### 3. 添加错误处理 + +```python +try: + response = agent.run("你的问题") +except Exception as e: + print(f"Error: {e}") +``` + +## 实践练习 + +尝试完成以下练习： + +1. **练习 1**：创建一个能够查询天气的 Agent +2. **练习 2**：实现一个简单的计算器 Agent +3. **练习 3**：开发一个文件操作 Agent + +提示：查看 [实践案例](04-practical-examples.md) 获取更多示例。 + +## 下一步 + +- 学习 [核心概念](03-core-concepts.md) 深入理解 Agent 原理 +- 查看 [实践案例](04-practical-examples.md) 了解更多应用场景 +- 阅读 [最佳实践](05-best-practices.md) 提高开发技能 + +## 资源链接 + +- [LangChain 快速开始](https://python.langchain.com/docs/get_started/quickstart) +- [OpenAI API 文档](https://platform.openai.com/docs/api-reference) +- [示例代码仓库](../examples/) diff --git a/tutorials/03-core-concepts.md b/tutorials/03-core-concepts.md new file mode 100644 index 0000000..0146aeb --- /dev/null +++ b/tutorials/03-core-concepts.md @@ -0,0 +1,388 @@ +# 核心概念 + +深入理解 Agent 的核心概念和关键组件，掌握 Agent 系统的工作原理。 + +## Agent 架构 + +### 基本架构图 + +``` +┌─────────────────────────────────────────────┐ +│ 用户交互层 │ +│ (User Interface) │ +└───────────────┬─────────────────────────────┘ + │ +┌───────────────▼─────────────────────────────┐ +│ Agent 核心 │ +│ ┌──────────────────────────────────────┐ │ +│ │ 大语言模型 (LLM) │ │ +│ │ - 理解与推理 │ │ +│ │ - 决策与规划 │ │ +│ └──────────────────────────────────────┘ │ +└───┬────────────┬────────────┬──────────────┘ + │ │ │ +┌───▼────┐ ┌───▼────┐ ┌───▼────┐ +│ 工具层 │ │ 记忆层 │ │ 规划层 │ +│ Tools │ │ Memory │ │Planner │ +└────────┘ └────────┘ └────────┘ +``` + +## 1. 大语言模型（LLM） + +LLM 是 Agent 的核心"大脑"，负责理解、推理和决策。 + +### 关键特性 + +- **自然语言理解**：理解用户意图 +- **推理能力**：逻辑推理和问题分析 +- **知识储备**：丰富的世界知识 +- **生成能力**：生成文本和代码 + +### 选择 LLM 的考虑因素 + +| 因素 | 说明 | 推荐 | +|------|------|------| +| 性能 | 响应速度和准确度 | GPT-4 > GPT-3.5 | +| 成本 | API 调用费用 | GPT-3.5 更经济 | +| 上下文长度 | 支持的 token 数量 | GPT-4-32k 最大 | +| 特定能力 | 代码、推理等 | 根据需求选择 | + +### 示例：配置不同的 LLM + +```python +from langchain.chat_models import ChatOpenAI + +# GPT-3.5 - 快速且经济 +llm_fast = ChatOpenAI( + model="gpt-3.5-turbo", + temperature=0 +) + +# GPT-4 - 更强大但较慢 +llm_powerful = ChatOpenAI( + model="gpt-4", + temperature=0 +) + +# 自定义参数 +llm_custom = ChatOpenAI( + model="gpt-3.5-turbo", + temperature=0.7, # 控制创造性 + max_tokens=1000, # 限制输出长度 + presence_penalty=0.5 # 避免重复 +) +``` + +## 2. 工具系统（Tools） + +工具是 Agent 与外部世界交互的接口，扩展了 Agent 的能力。 + +### 工具的组成 + +1. **名称（Name）**：工具的唯一标识 +2. **描述（Description）**：告诉 Agent 工具的功能 +3. **函数（Function）**：实际执行的代码 +4. **参数（Arguments）**：工具需要的输入 + +### 创建自定义工具 + +```python +from langchain.tools import Tool +from langchain.tools import BaseTool +from pydantic import BaseModel, Field + +# 方法 1: 使用 Tool 类 +def search_database(query: str) -> str: + """在数据库中搜索信息""" + # 实现搜索逻辑 + return f"搜索结果：{query}" + +search_tool = Tool( + name="DatabaseSearch", + func=search_database, + description="在数据库中搜索信息。输入应该是搜索查询。" +) + +# 方法 2: 继承 BaseTool +class CustomSearchTool(BaseTool): + name = "CustomSearch" + description = "自定义搜索工具" + + def _run(self, query: str) -> str: + """同步执行""" + return f"搜索：{query}" + + async def _arun(self, query: str) -> str: + """异步执行""" + return f"异步搜索：{query}" + +# 方法 3: 使用 @tool 装饰器 +from langchain.tools import tool + +@tool +def calculate_sum(numbers: str) -> str: + """计算数字的和。输入应该是逗号分隔的数字。""" + nums = [float(n.strip()) for n in numbers.split(',')] + return str(sum(nums)) +``` + +### 内置工具示例 + +```python +from langchain.agents import load_tools + +# 加载内置工具 +tools = load_tools( + [ + "python_repl", # Python 执行 + "requests_get", # HTTP GET 请求 + "terminal", # 终端命令 + "wikipedia", # 维基百科查询 + "google-search", # Google 搜索 + ], + llm=llm +) +``` + +### 工具设计最佳实践 + +1. **清晰的描述**：让 Agent 准确理解工具用途 +2. **合理的粒度**：不要太复杂也不要太简单 +3. **错误处理**：优雅地处理异常情况 +4. **性能考虑**：避免长时间运行的操作 + +## 3. 记忆系统（Memory） + +记忆系统使 Agent 能够记住历史信息，实现连贯的对话。 + +### 记忆类型 + +#### 3.1 对话缓冲记忆（ConversationBufferMemory） + +保存所有历史对话： + +```python +from langchain.memory import ConversationBufferMemory + +memory = ConversationBufferMemory( + memory_key="chat_history", + return_messages=True +) +``` + +#### 3.2 对话摘要记忆（ConversationSummaryMemory） + +对历史对话进行摘要： + +```python +from langchain.memory import ConversationSummaryMemory + +memory = ConversationSummaryMemory( + llm=llm, + memory_key="chat_history" +) +``` + +#### 3.3 对话窗口记忆（ConversationBufferWindowMemory） + +只保留最近 K 轮对话： + +```python +from langchain.memory import ConversationBufferWindowMemory + +memory = ConversationBufferWindowMemory( + k=5, # 保留最近 5 轮对话 + memory_key="chat_history" +) +``` + +#### 3.4 实体记忆（ConversationEntityMemory） + +记住对话中的关键实体： + +```python +from langchain.memory import ConversationEntityMemory + +memory = ConversationEntityMemory( + llm=llm, + memory_key="entity_memory" +) +``` + +### 使用记忆的 Agent + +```python +from langchain.agents import initialize_agent +from langchain.memory import ConversationBufferMemory + +memory = ConversationBufferMemory( + memory_key="chat_history", + return_messages=True +) + +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION, + memory=memory, # 添加记忆 + verbose=True +) + +# 第一次对话 +response1 = agent.run("我叫张三") +# 第二次对话 - Agent 会记住之前的对话 +response2 = agent.run("我叫什么名字？") +``` + +## 4. 规划系统（Planning） + +规划系统负责将复杂任务分解为可执行的步骤。 + +### ReAct 模式 + +ReAct (Reasoning + Acting) 是最常用的规划模式： + +``` +Thought: 我需要做什么？ +Action: 选择要使用的工具 +Action Input: 工具的输入 +Observation: 工具的输出 +... (重复上述过程) +Thought: 我现在知道答案了 +Final Answer: 最终答案 +``` + +### 示例：ReAct 过程 + +``` +问题：今天北京的天气如何？明天适合户外活动吗？ + +Thought: 我需要先查询今天北京的天气 +Action: WeatherQuery +Action Input: 北京，今天 +Observation: 北京今天晴，气温 20-28°C + +Thought: 现在我需要查询明天的天气 +Action: WeatherQuery +Action Input: 北京，明天 +Observation: 北京明天多云，气温 18-25°C + +Thought: 根据天气情况，我可以给出建议了 +Final Answer: 今天北京天气晴朗，气温 20-28°C。 +明天多云，气温 18-25°C，天气适宜户外活动。 +``` + +### Plan-and-Execute 模式 + +适合更复杂的任务： + +```python +from langchain.experimental.plan_and_execute import ( + PlanAndExecute, + load_agent_executor, + load_chat_planner +) + +planner = load_chat_planner(llm) +executor = load_agent_executor(llm, tools, verbose=True) + +agent = PlanAndExecute( + planner=planner, + executor=executor, + verbose=True +) +``` + +## 5. 提示工程（Prompt Engineering） + +### System Prompt 设计 + +```python +system_prompt = """ +你是一个专业的数据分析助手。 + +你的职责是： +1. 帮助用户分析数据 +2. 生成可视化图表 +3. 提供数据洞察 + +工作原则： +- 始终基于数据事实 +- 提供清晰的解释 +- 避免过度推测 + +可用工具： +- DataQuery: 查询数据 +- PlotChart: 生成图表 +- Statistics: 计算统计指标 +""" +``` + +### Few-Shot Learning + +通过示例提升性能： + +```python +examples = """ +示例 1: +用户: 帮我计算平均值 +思考: 我需要使用 Statistics 工具 +动作: Statistics +输入: average + +示例 2: +用户: 显示销售趋势 +思考: 我需要先查询数据，然后绘制图表 +动作: DataQuery +输入: sales_data +""" +``` + +## 6. 错误处理与重试 + +### 实现重试机制 + +```python +from langchain.agents import AgentExecutor + +agent_executor = AgentExecutor( + agent=agent, + tools=tools, + max_iterations=5, # 最大迭代次数 + max_execution_time=60, # 最大执行时间（秒） + early_stopping_method="generate", # 提前停止策略 + handle_parsing_errors=True, # 处理解析错误 +) +``` + +### 自定义错误处理 + +```python +def handle_tool_error(error: Exception) -> str: + """自定义错误处理""" + return f"工具执行出错：{str(error)}。请尝试其他方法。" + +tool = Tool( + name="MyTool", + func=my_function, + description="工具描述", + handle_tool_error=handle_tool_error +) +``` + +## 总结 + +本章介绍了 Agent 的核心概念： + +- ✅ LLM 作为 Agent 的大脑 +- ✅ 工具系统扩展 Agent 能力 +- ✅ 记忆系统保持对话连贯性 +- ✅ 规划系统实现任务分解 +- ✅ 提示工程优化 Agent 行为 +- ✅ 错误处理保证系统稳定性 + +## 下一步 + +- 查看 [实践案例](04-practical-examples.md) 学习实际应用 +- 阅读 [最佳实践](05-best-practices.md) 提升开发技能 +- 探索 [高级主题](06-advanced-topics.md) 掌握进阶技术 diff --git a/tutorials/04-practical-examples.md b/tutorials/04-practical-examples.md new file mode 100644 index 0000000..f08e35c --- /dev/null +++ b/tutorials/04-practical-examples.md @@ -0,0 +1,471 @@ +# 实践案例 + +通过实际案例学习 Agent 的应用，从简单到复杂逐步提升。 + +## 案例 1：智能对话助手 + +创建一个能够回答问题并执行简单任务的对话助手。 + +### 代码实现 + +```python +from langchain.agents import initialize_agent, AgentType +from langchain.chat_models import ChatOpenAI +from langchain.tools import Tool +from datetime import datetime +import json + +# 初始化 LLM +llm = ChatOpenAI(temperature=0, model="gpt-3.5-turbo") + +# 定义工具函数 +def get_time(): + """获取当前时间""" + return datetime.now().strftime("%Y-%m-%d %H:%M:%S") + +def calculate(expression: str) -> str: + """执行数学计算""" + try: + result = eval(expression) + return f"计算结果：{result}" + except Exception as e: + return f"计算出错：{str(e)}" + +def save_note(content: str) -> str: + """保存笔记到文件""" + with open("notes.txt", "a", encoding="utf-8") as f: + f.write(f"[{datetime.now()}] {content}\n") + return "笔记已保存" + +# 创建工具列表 +tools = [ + Tool(name="GetTime", func=get_time, + description="获取当前日期和时间"), + Tool(name="Calculate", func=calculate, + description="执行数学计算。输入应该是一个数学表达式，如 '2+3' 或 '10*5'"), + Tool(name="SaveNote", func=save_note, + description="保存笔记。输入应该是要保存的笔记内容"), +] + +# 初始化 Agent +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True +) + +# 测试对话 +if __name__ == "__main__": + queries = [ + "现在几点了？", + "帮我计算 123 * 456", + "请帮我记录：今天学习了 Agent 开发", + ] + + for query in queries: + print(f"\n{'='*50}") + print(f"问题：{query}") + print(f"{'='*50}") + response = agent.run(query) + print(f"回答：{response}\n") +``` + +### 运行效果 + +``` +================================================== +问题：现在几点了？ +================================================== +> Entering new AgentExecutor chain... +Action: GetTime +Observation: 2024-01-15 14:30:25 +Final Answer: 现在是 2024年1月15日 14:30:25 +回答：现在是 2024年1月15日 14:30:25 +``` + +## 案例 2：数据分析 Agent + +创建一个能够分析数据、生成统计报告的 Agent。 + +### 代码实现 + +```python +from langchain.agents import initialize_agent, AgentType +from langchain.chat_models import ChatOpenAI +from langchain.tools import Tool +import pandas as pd +import matplotlib.pyplot as plt +import json + +llm = ChatOpenAI(temperature=0, model="gpt-3.5-turbo") + +# 模拟数据 +sales_data = pd.DataFrame({ + '日期': pd.date_range('2024-01-01', periods=30), + '销售额': [1000 + i * 50 + (i % 7) * 100 for i in range(30)], + '订单数': [20 + i + (i % 5) * 3 for i in range(30)] +}) + +def query_data(query_type: str) -> str: + """查询数据""" + if query_type == "summary": + return sales_data.describe().to_json() + elif query_type == "total": + return f"总销售额: {sales_data['销售额'].sum()}, 总订单数: {sales_data['订单数'].sum()}" + elif query_type == "average": + return f"平均销售额: {sales_data['销售额'].mean():.2f}, 平均订单数: {sales_data['订单数'].mean():.2f}" + return "请指定 summary, total, 或 average" + +def calculate_growth(metric: str) -> str: + """计算增长率""" + if metric == "sales": + first_week = sales_data['销售额'][:7].mean() + last_week = sales_data['销售额'][-7:].mean() + growth = ((last_week - first_week) / first_week) * 100 + return f"销售额增长率: {growth:.2f}%" + elif metric == "orders": + first_week = sales_data['订单数'][:7].mean() + last_week = sales_data['订单数'][-7:].mean() + growth = ((last_week - first_week) / first_week) * 100 + return f"订单数增长率: {growth:.2f}%" + return "请指定 sales 或 orders" + +def generate_chart(chart_type: str) -> str: + """生成图表""" + plt.figure(figsize=(10, 6)) + if chart_type == "sales": + plt.plot(sales_data['日期'], sales_data['销售额']) + plt.title('销售额趋势') + plt.ylabel('销售额') + elif chart_type == "orders": + plt.plot(sales_data['日期'], sales_data['订单数']) + plt.title('订单数趋势') + plt.ylabel('订单数') + else: + return "请指定 sales 或 orders" + + plt.xlabel('日期') + plt.xticks(rotation=45) + plt.tight_layout() + plt.savefig(f'{chart_type}_chart.png') + plt.close() + return f"图表已保存为 {chart_type}_chart.png" + +tools = [ + Tool(name="QueryData", func=query_data, + description="查询数据。输入 'summary' 获取统计摘要，'total' 获取总计，'average' 获取平均值"), + Tool(name="CalculateGrowth", func=calculate_growth, + description="计算增长率。输入 'sales' 计算销售额增长率，'orders' 计算订单数增长率"), + Tool(name="GenerateChart", func=generate_chart, + description="生成趋势图表。输入 'sales' 生成销售额图表，'orders' 生成订单数图表"), +] + +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True +) + +if __name__ == "__main__": + # 数据分析任务 + tasks = [ + "给我一个数据摘要", + "销售额的增长情况如何？", + "生成销售额趋势图", + ] + + for task in tasks: + print(f"\n任务：{task}") + response = agent.run(task) + print(f"结果：{response}\n") +``` + +## 案例 3：文件管理 Agent + +创建一个能够管理文件和目录的 Agent。 + +### 代码实现 + +```python +from langchain.agents import initialize_agent, AgentType +from langchain.chat_models import ChatOpenAI +from langchain.tools import Tool +import os +import shutil +from pathlib import Path + +llm = ChatOpenAI(temperature=0) + +# 工作目录 +WORK_DIR = "./agent_workspace" +os.makedirs(WORK_DIR, exist_ok=True) + +def list_files(directory: str = ".") -> str: + """列出目录中的文件""" + path = Path(WORK_DIR) / directory + if not path.exists(): + return f"目录不存在: {directory}" + + files = [] + for item in path.iterdir(): + item_type = "目录" if item.is_dir() else "文件" + files.append(f"{item_type}: {item.name}") + + return "\n".join(files) if files else "目录为空" + +def create_file(filename: str, content: str = "") -> str: + """创建文件""" + path = Path(WORK_DIR) / filename + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content, encoding="utf-8") + return f"文件已创建: {filename}" + +def read_file(filename: str) -> str: + """读取文件内容""" + path = Path(WORK_DIR) / filename + if not path.exists(): + return f"文件不存在: {filename}" + return path.read_text(encoding="utf-8") + +def delete_file(filename: str) -> str: + """删除文件""" + path = Path(WORK_DIR) / filename + if not path.exists(): + return f"文件不存在: {filename}" + path.unlink() + return f"文件已删除: {filename}" + +def create_directory(dirname: str) -> str: + """创建目录""" + path = Path(WORK_DIR) / dirname + path.mkdir(parents=True, exist_ok=True) + return f"目录已创建: {dirname}" + +tools = [ + Tool(name="ListFiles", func=list_files, + description="列出目录中的文件和子目录。输入目录路径，默认为当前目录"), + Tool(name="CreateFile", func=lambda x: create_file(*x.split('|', 1)), + description="创建文件。输入格式：文件名|文件内容"), + Tool(name="ReadFile", func=read_file, + description="读取文件内容。输入文件名"), + Tool(name="DeleteFile", func=delete_file, + description="删除文件。输入文件名"), + Tool(name="CreateDirectory", func=create_directory, + description="创建目录。输入目录名"), +] + +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True +) + +if __name__ == "__main__": + commands = [ + "创建一个名为 test.txt 的文件，内容是 'Hello, Agent!'", + "列出所有文件", + "读取 test.txt 的内容", + "创建一个名为 docs 的目录", + ] + + for cmd in commands: + print(f"\n命令：{cmd}") + response = agent.run(cmd) + print(f"结果：{response}") +``` + +## 案例 4：代码生成 Agent + +创建一个能够生成和执行代码的 Agent。 + +### 代码实现 + +```python +from langchain.agents import initialize_agent, AgentType, load_tools +from langchain.chat_models import ChatOpenAI +from langchain.tools import Tool +import subprocess + +llm = ChatOpenAI(temperature=0, model="gpt-4") + +def generate_code(description: str) -> str: + """根据描述生成代码""" + prompt = f"请生成Python代码实现以下功能：{description}\n只返回代码，不要解释。" + response = llm.predict(prompt) + return response + +def execute_code(code: str) -> str: + """执行Python代码""" + try: + # 保存代码到临时文件 + with open("temp_code.py", "w", encoding="utf-8") as f: + f.write(code) + + # 执行代码 + result = subprocess.run( + ["python", "temp_code.py"], + capture_output=True, + text=True, + timeout=10 + ) + + if result.returncode == 0: + return f"执行成功:\n{result.stdout}" + else: + return f"执行失败:\n{result.stderr}" + except Exception as e: + return f"执行错误: {str(e)}" + +def save_code(filename: str, code: str) -> str: + """保存代码到文件""" + with open(filename, "w", encoding="utf-8") as f: + f.write(code) + return f"代码已保存到: {filename}" + +tools = [ + Tool(name="GenerateCode", func=generate_code, + description="根据功能描述生成Python代码"), + Tool(name="ExecuteCode", func=execute_code, + description="执行Python代码。输入应该是完整的Python代码"), + Tool(name="SaveCode", func=lambda x: save_code(*x.split('|', 1)), + description="保存代码到文件。输入格式：文件名|代码内容"), +] + +# 加载 Python REPL 工具 +python_repl = load_tools(["python_repl"], llm=llm) +tools.extend(python_repl) + +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True, + handle_parsing_errors=True +) + +if __name__ == "__main__": + tasks = [ + "生成一个计算斐波那契数列的函数", + "生成一个读取CSV文件并计算平均值的脚本", + ] + + for task in tasks: + print(f"\n任务：{task}") + response = agent.run(task) + print(f"结果：{response}") +``` + +## 案例 5：多功能助手（综合案例） + +结合多种功能的综合助手。 + +### 代码实现 + +```python +from langchain.agents import initialize_agent, AgentType +from langchain.chat_models import ChatOpenAI +from langchain.memory import ConversationBufferMemory +from langchain.tools import Tool +import requests +from datetime import datetime + +llm = ChatOpenAI(temperature=0.7, model="gpt-3.5-turbo") + +# 创建记忆 +memory = ConversationBufferMemory( + memory_key="chat_history", + return_messages=True +) + +# 定义各种工具 +def get_weather(city: str) -> str: + """获取天气信息（模拟）""" + # 实际应用中应调用天气 API + return f"{city}的天气：晴，温度20-28°C" + +def search_web(query: str) -> str: + """网络搜索（模拟）""" + return f"搜索'{query}'的结果：[相关信息]" + +def set_reminder(reminder: str) -> str: + """设置提醒""" + with open("reminders.txt", "a", encoding="utf-8") as f: + f.write(f"[{datetime.now()}] {reminder}\n") + return "提醒已设置" + +def translate_text(text: str) -> str: + """翻译文本（模拟）""" + # 实际应用中应调用翻译 API + return f"翻译结果：{text}" + +tools = [ + Tool(name="GetWeather", func=get_weather, + description="获取指定城市的天气信息"), + Tool(name="SearchWeb", func=search_web, + description="在网络上搜索信息"), + Tool(name="SetReminder", func=set_reminder, + description="设置提醒事项"), + Tool(name="TranslateText", func=translate_text, + description="翻译文本"), +] + +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION, + memory=memory, + verbose=True +) + +if __name__ == "__main__": + # 交互式对话 + print("多功能助手已启动！输入 'quit' 退出。\n") + + while True: + user_input = input("您: ") + if user_input.lower() == 'quit': + break + + response = agent.run(user_input) + print(f"助手: {response}\n") +``` + +## 实践建议 + +### 1. 从简单开始 +- 先实现基本功能 +- 逐步添加新工具 +- 测试每个组件 + +### 2. 工具设计 +- 保持工具功能单一 +- 提供清晰的描述 +- 处理边界情况 + +### 3. 错误处理 +- 添加异常捕获 +- 提供有用的错误信息 +- 实现重试机制 + +### 4. 性能优化 +- 缓存常用结果 +- 异步执行耗时操作 +- 限制迭代次数 + +## 下一步 + +- 学习 [最佳实践](05-best-practices.md) 优化您的 Agent +- 探索 [高级主题](06-advanced-topics.md) 深入研究 +- 查看更多示例代码在 [examples](../examples/) 目录 + +## 练习题 + +1. 实现一个待办事项管理 Agent +2. 创建一个代码审查 Agent +3. 开发一个数据可视化 Agent +4. 构建一个文档生成 Agent + +试着结合多个工具，创造您自己的 Agent 应用！ diff --git a/tutorials/05-best-practices.md b/tutorials/05-best-practices.md new file mode 100644 index 0000000..f6fe610 --- /dev/null +++ b/tutorials/05-best-practices.md @@ -0,0 +1,579 @@ +# 最佳实践 + +学习 Agent 开发的最佳实践，提升代码质量和系统性能。 + +## 1. Prompt 工程技巧 + +### 1.1 清晰的系统提示 + +好的系统提示能显著提升 Agent 性能： + +```python +system_prompt = """ +你是一个专业的 {role}。 + +职责： +- {responsibility_1} +- {responsibility_2} +- {responsibility_3} + +工作原则： +- {principle_1} +- {principle_2} + +注意事项： +- {note_1} +- {note_2} +""" +``` + +**示例：** + +```python +data_analyst_prompt = """ +你是一个专业的数据分析师。 + +职责： +- 分析数据并发现模式 +- 生成可视化图表 +- 提供数据驱动的洞察 + +工作原则： +- 始终基于实际数据 +- 保持客观中立 +- 提供可操作的建议 + +注意事项： +- 避免过度推测 +- 说明分析的局限性 +- 使用清晰的语言解释技术概念 +""" +``` + +### 1.2 结构化输出 + +要求 Agent 使用特定格式输出： + +```python +format_instructions = """ +请按以下格式回答： + +分析结果： +- 关键发现1 +- 关键发现2 + +建议： +- 建议1 +- 建议2 + +置信度：[高/中/低] +""" +``` + +### 1.3 Few-Shot 示例 + +提供示例帮助 Agent 理解任务： + +```python +few_shot_examples = """ +示例 1: +输入：分析销售数据 +输出： +1. 数据概览：总销售额 100万，订单数 5000 +2. 趋势分析：呈上升趋势，增长率 15% +3. 建议：继续当前策略，关注高价值客户 + +示例 2: +输入：查找异常值 +输出： +1. 检测到 3 个异常值 +2. 异常日期：2024-01-05, 2024-01-12, 2024-01-20 +3. 可能原因：促销活动、系统错误 +""" +``` + +## 2. Agent 设计原则 + +### 2.1 单一职责原则 + +每个工具应该只做一件事： + +```python +# ❌ 不好的设计 - 工具功能过于复杂 +def process_data_and_create_report(data, report_type, format, email): + # 处理数据 + # 创建报告 + # 发送邮件 + pass + +# ✅ 好的设计 - 功能分离 +def process_data(data): + """只负责处理数据""" + pass + +def create_report(processed_data, report_type): + """只负责创建报告""" + pass + +def send_email(report, recipient): + """只负责发送邮件""" + pass +``` + +### 2.2 清晰的工具描述 + +工具描述直接影响 Agent 的选择： + +```python +# ❌ 描述不清晰 +Tool( + name="DataTool", + func=process, + description="处理数据" +) + +# ✅ 描述清晰具体 +Tool( + name="CalculateAverage", + func=calculate_average, + description=""" + 计算数值列表的平均值。 + + 输入：逗号分隔的数字字符串，例如 "1,2,3,4,5" + 输出：平均值，保留两位小数 + + 使用场景： + - 需要计算平均值时 + - 输入是数字列表时 + """ +) +``` + +### 2.3 适当的工具粒度 + +```python +# ❌ 粒度过细 +Tool(name="Add", func=add, description="两数相加") +Tool(name="Subtract", func=subtract, description="两数相减") +Tool(name="Multiply", func=multiply, description="两数相乘") +Tool(name="Divide", func=divide, description="两数相除") + +# ✅ 合理的粒度 +Tool( + name="Calculate", + func=calculate, + description=""" + 执行数学计算。 + 支持加减乘除和基本数学函数。 + 输入：数学表达式，如 "2 + 3 * 4" 或 "sqrt(16)" + """ +) +``` + +### 2.4 错误处理和验证 + +```python +from pydantic import BaseModel, Field, validator + +class CalculatorInput(BaseModel): + """计算器输入验证""" + expression: str = Field(description="数学表达式") + + @validator('expression') + def validate_expression(cls, v): + """验证表达式安全性""" + # 只允许特定字符 + allowed = set('0123456789+-*/()., ') + if not all(c in allowed for c in v): + raise ValueError("表达式包含不允许的字符") + return v + +def safe_calculate(expression: str) -> str: + """安全的计算函数""" + try: + # 验证输入 + input_data = CalculatorInput(expression=expression) + + # 执行计算 + result = eval(input_data.expression) + return f"结果：{result}" + + except ValueError as e: + return f"输入错误：{str(e)}" + except ZeroDivisionError: + return "错误：除数不能为零" + except Exception as e: + return f"计算错误：{str(e)}" +``` + +## 3. 性能优化 + +### 3.1 缓存机制 + +```python +from functools import lru_cache +from datetime import datetime, timedelta + +class CachedAgent: + def __init__(self): + self.cache = {} + self.cache_duration = timedelta(minutes=5) + + def get_with_cache(self, key, fetch_func): + """带缓存的数据获取""" + now = datetime.now() + + # 检查缓存 + if key in self.cache: + data, timestamp = self.cache[key] + if now - timestamp < self.cache_duration: + return data + + # 获取新数据 + data = fetch_func() + self.cache[key] = (data, now) + return data + +# 使用装饰器缓存 +@lru_cache(maxsize=100) +def expensive_operation(param): + """耗时操作""" + # 执行复杂计算 + return result +``` + +### 3.2 异步执行 + +```python +import asyncio +from langchain.tools import BaseTool + +class AsyncSearchTool(BaseTool): + name = "AsyncSearch" + description = "异步搜索工具" + + async def _arun(self, query: str) -> str: + """异步执行""" + # 并发执行多个搜索 + tasks = [ + self.search_source1(query), + self.search_source2(query), + self.search_source3(query), + ] + results = await asyncio.gather(*tasks) + return self.merge_results(results) + + def _run(self, query: str) -> str: + """同步执行（回退）""" + return asyncio.run(self._arun(query)) +``` + +### 3.3 限制迭代次数 + +```python +from langchain.agents import AgentExecutor + +agent_executor = AgentExecutor( + agent=agent, + tools=tools, + max_iterations=10, # 最大迭代次数 + max_execution_time=60, # 最大执行时间（秒） + early_stopping_method="force" # 强制停止 +) +``` + +### 3.4 选择合适的模型 + +```python +# 根据任务复杂度选择模型 +simple_llm = ChatOpenAI(model="gpt-3.5-turbo") # 简单任务 +complex_llm = ChatOpenAI(model="gpt-4") # 复杂任务 + +# 使用不同模型处理不同任务 +if task_complexity == "simple": + agent = initialize_agent(tools, simple_llm, ...) +else: + agent = initialize_agent(tools, complex_llm, ...) +``` + +## 4. 安全性考虑 + +### 4.1 输入验证 + +```python +def validate_input(user_input: str) -> bool: + """验证用户输入""" + # 长度检查 + if len(user_input) > 1000: + return False + + # 危险字符检查 + dangerous_patterns = ['rm -rf', 'DROP TABLE', 'eval(', 'exec('] + if any(pattern in user_input for pattern in dangerous_patterns): + return False + + return True + +# 在 Agent 中使用 +if not validate_input(user_input): + return "输入包含不安全内容" +``` + +### 4.2 工具权限控制 + +```python +class RestrictedTool(BaseTool): + """受限工具""" + name = "RestrictedOperation" + allowed_users = ["admin", "power_user"] + + def _run(self, query: str, user: str) -> str: + # 检查权限 + if user not in self.allowed_users: + return "权限不足" + + # 执行操作 + return self.execute(query) +``` + +### 4.3 敏感信息处理 + +```python +def sanitize_output(text: str) -> str: + """清理输出中的敏感信息""" + import re + + # 隐藏邮箱 + text = re.sub(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', + '***@***.***', text) + + # 隐藏手机号 + text = re.sub(r'\b1[3-9]\d{9}\b', '***********', text) + + # 隐藏身份证号 + text = re.sub(r'\b\d{17}[\dXx]\b', '******************', text) + + return text +``` + +## 5. 测试策略 + +### 5.1 单元测试 + +```python +import unittest +from unittest.mock import Mock, patch + +class TestAgentTools(unittest.TestCase): + def test_calculate_tool(self): + """测试计算工具""" + result = calculate("2 + 3") + self.assertEqual(result, "5") + + def test_calculate_error(self): + """测试错误处理""" + result = calculate("invalid") + self.assertIn("错误", result) + + @patch('requests.get') + def test_api_call(self, mock_get): + """测试 API 调用""" + mock_get.return_value.json.return_value = {"data": "test"} + result = fetch_data("query") + self.assertEqual(result, {"data": "test"}) +``` + +### 5.2 集成测试 + +```python +def test_agent_flow(): + """测试完整 Agent 流程""" + agent = create_test_agent() + + # 测试场景1：简单查询 + response = agent.run("现在几点？") + assert "时间" in response or "点" in response + + # 测试场景2：多步骤任务 + response = agent.run("查询天气并保存结果") + assert "已保存" in response + + # 测试场景3：错误处理 + response = agent.run("执行不可能的任务") + assert "无法" in response or "错误" in response +``` + +### 5.3 性能测试 + +```python +import time + +def benchmark_agent(agent, test_queries, iterations=10): + """性能基准测试""" + times = [] + + for _ in range(iterations): + start = time.time() + for query in test_queries: + agent.run(query) + end = time.time() + times.append(end - start) + + avg_time = sum(times) / len(times) + print(f"平均执行时间：{avg_time:.2f}秒") + print(f"最快：{min(times):.2f}秒") + print(f"最慢：{max(times):.2f}秒") +``` + +## 6. 监控和日志 + +### 6.1 结构化日志 + +```python +import logging +import json +from datetime import datetime + +class AgentLogger: + def __init__(self): + self.logger = logging.getLogger('agent') + self.logger.setLevel(logging.INFO) + + # 文件处理器 + handler = logging.FileHandler('agent.log') + handler.setFormatter( + logging.Formatter('%(asctime)s - %(message)s') + ) + self.logger.addHandler(handler) + + def log_interaction(self, user_input, agent_output, tools_used): + """记录交互""" + log_entry = { + 'timestamp': datetime.now().isoformat(), + 'input': user_input, + 'output': agent_output, + 'tools': tools_used, + } + self.logger.info(json.dumps(log_entry, ensure_ascii=False)) +``` + +### 6.2 性能监控 + +```python +from functools import wraps +import time + +def monitor_performance(func): + """性能监控装饰器""" + @wraps(func) + def wrapper(*args, **kwargs): + start = time.time() + result = func(*args, **kwargs) + duration = time.time() - start + + # 记录性能数据 + print(f"{func.__name__} 执行时间：{duration:.2f}秒") + + # 如果执行时间过长，发出警告 + if duration > 10: + print(f"警告：{func.__name__} 执行时间过长") + + return result + return wrapper + +@monitor_performance +def agent_run(query): + return agent.run(query) +``` + +## 7. 文档和维护 + +### 7.1 工具文档 + +```python +def comprehensive_tool_example(param1: str, param2: int = 10) -> str: + """ + 工具功能的简短描述 + + 详细说明： + 这个工具用于... + + 参数： + param1 (str): 第一个参数的说明 + param2 (int, optional): 第二个参数的说明，默认为 10 + + 返回： + str: 返回值的说明 + + 示例： + >>> comprehensive_tool_example("test", 20) + "处理结果" + + 注意事项： + - 注意事项1 + - 注意事项2 + """ + pass +``` + +### 7.2 版本控制 + +```python +# 工具版本管理 +TOOL_VERSION = "1.0.0" + +class VersionedTool(BaseTool): + name = "VersionedTool" + version = TOOL_VERSION + + def _run(self, query: str) -> str: + # 根据版本处理不同逻辑 + if self.version >= "2.0.0": + return self.new_implementation(query) + else: + return self.old_implementation(query) +``` + +## 最佳实践清单 + +✅ Prompt 工程 +- [ ] 使用清晰的系统提示 +- [ ] 提供结构化输出格式 +- [ ] 添加 Few-Shot 示例 + +✅ 设计原则 +- [ ] 工具功能单一 +- [ ] 描述清晰具体 +- [ ] 合理的粒度 + +✅ 性能优化 +- [ ] 实现缓存机制 +- [ ] 使用异步执行 +- [ ] 限制迭代次数 +- [ ] 选择合适模型 + +✅ 安全性 +- [ ] 验证用户输入 +- [ ] 控制工具权限 +- [ ] 处理敏感信息 + +✅ 测试 +- [ ] 编写单元测试 +- [ ] 进行集成测试 +- [ ] 执行性能测试 + +✅ 监控 +- [ ] 添加结构化日志 +- [ ] 监控性能指标 +- [ ] 设置告警机制 + +✅ 文档 +- [ ] 编写详细文档 +- [ ] 添加使用示例 +- [ ] 维护版本信息 + +## 下一步 + +- 探索 [高级主题](06-advanced-topics.md) 学习更多技术 +- 查看 [常见问题](07-troubleshooting.md) 解决问题 +- 参考 [资源列表](08-resources.md) 深入学习 diff --git a/tutorials/06-advanced-topics.md b/tutorials/06-advanced-topics.md new file mode 100644 index 0000000..0b8fcbf --- /dev/null +++ b/tutorials/06-advanced-topics.md @@ -0,0 +1,684 @@ +# 高级主题 + +深入探索 Agent 开发的高级技术和复杂应用场景。 + +## 1. 多 Agent 系统 + +多个 Agent 协作可以处理更复杂的任务。 + +### 1.1 基本多 Agent 架构 + +```python +from langchain.agents import initialize_agent, AgentType +from langchain.chat_models import ChatOpenAI + +class MultiAgentSystem: + def __init__(self): + self.llm = ChatOpenAI(temperature=0) + + # 创建专门的 Agent + self.researcher = self.create_researcher() + self.analyst = self.create_analyst() + self.writer = self.create_writer() + + def create_researcher(self): + """研究员 Agent""" + tools = [...] # 搜索工具 + return initialize_agent( + tools, self.llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION + ) + + def create_analyst(self): + """分析师 Agent""" + tools = [...] # 分析工具 + return initialize_agent( + tools, self.llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION + ) + + def create_writer(self): + """写作者 Agent""" + tools = [...] # 写作工具 + return initialize_agent( + tools, self.llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION + ) + + def process_task(self, task): + """处理任务的流程""" + # 1. 研究员收集信息 + research_result = self.researcher.run( + f"收集关于 {task} 的信息" + ) + + # 2. 分析师分析数据 + analysis_result = self.analyst.run( + f"分析以下信息：{research_result}" + ) + + # 3. 写作者生成报告 + final_report = self.writer.run( + f"基于以下分析写一份报告：{analysis_result}" + ) + + return final_report + +# 使用示例 +system = MultiAgentSystem() +result = system.process_task("人工智能的最新发展") +``` + +### 1.2 Agent 通信机制 + +```python +from typing import List, Dict +import json + +class AgentCommunicationHub: + """Agent 通信中心""" + + def __init__(self): + self.agents: Dict[str, Agent] = {} + self.message_queue = [] + + def register_agent(self, name: str, agent): + """注册 Agent""" + self.agents[name] = agent + + def send_message(self, from_agent: str, to_agent: str, message: str): + """发送消息""" + self.message_queue.append({ + 'from': from_agent, + 'to': to_agent, + 'message': message, + 'timestamp': datetime.now() + }) + + def get_messages(self, agent_name: str) -> List[Dict]: + """获取发给特定 Agent 的消息""" + return [ + msg for msg in self.message_queue + if msg['to'] == agent_name + ] + + def broadcast(self, from_agent: str, message: str): + """广播消息给所有 Agent""" + for agent_name in self.agents: + if agent_name != from_agent: + self.send_message(from_agent, agent_name, message) + +# 使用示例 +hub = AgentCommunicationHub() +hub.register_agent("researcher", researcher_agent) +hub.register_agent("analyst", analyst_agent) + +# 发送消息 +hub.send_message("researcher", "analyst", "这是收集到的数据") +``` + +### 1.3 协作模式 + +#### 顺序协作 + +```python +def sequential_collaboration(task): + """顺序协作模式""" + # Agent A -> Agent B -> Agent C + result_a = agent_a.run(task) + result_b = agent_b.run(f"基于 {result_a} 继续处理") + result_c = agent_c.run(f"最终处理 {result_b}") + return result_c +``` + +#### 并行协作 + +```python +import asyncio + +async def parallel_collaboration(task): + """并行协作模式""" + # 多个 Agent 同时工作 + tasks = [ + agent_a.arun(task), + agent_b.arun(task), + agent_c.arun(task), + ] + results = await asyncio.gather(*tasks) + + # 合并结果 + final_result = merge_results(results) + return final_result +``` + +#### 层级协作 + +```python +class HierarchicalAgentSystem: + """层级 Agent 系统""" + + def __init__(self): + self.manager = ManagerAgent() + self.workers = [ + WorkerAgent("worker1"), + WorkerAgent("worker2"), + WorkerAgent("worker3"), + ] + + def process(self, task): + # 管理者分配任务 + subtasks = self.manager.decompose_task(task) + + # 工作者执行子任务 + results = [] + for subtask, worker in zip(subtasks, self.workers): + result = worker.run(subtask) + results.append(result) + + # 管理者整合结果 + final_result = self.manager.aggregate(results) + return final_result +``` + +## 2. 长期记忆管理 + +### 2.1 向量数据库集成 + +```python +from langchain.vectorstores import Chroma +from langchain.embeddings import OpenAIEmbeddings +from langchain.memory import VectorStoreRetrieverMemory + +# 创建向量存储 +embeddings = OpenAIEmbeddings() +vectorstore = Chroma( + collection_name="agent_memory", + embedding_function=embeddings +) + +# 创建记忆系统 +memory = VectorStoreRetrieverMemory( + retriever=vectorstore.as_retriever(search_kwargs={"k": 5}) +) + +# 保存记忆 +memory.save_context( + {"input": "我喜欢吃苹果"}, + {"output": "好的，我记住了"} +) + +# 检索记忆 +relevant_memories = memory.load_memory_variables( + {"input": "我喜欢什么水果？"} +) +``` + +### 2.2 知识图谱 + +```python +import networkx as nx + +class KnowledgeGraph: + """知识图谱""" + + def __init__(self): + self.graph = nx.DiGraph() + + def add_entity(self, entity, entity_type, properties=None): + """添加实体""" + self.graph.add_node( + entity, + type=entity_type, + properties=properties or {} + ) + + def add_relation(self, entity1, entity2, relation): + """添加关系""" + self.graph.add_edge(entity1, entity2, relation=relation) + + def query(self, entity): + """查询实体的关系""" + if entity not in self.graph: + return None + + # 获取相关信息 + neighbors = list(self.graph.neighbors(entity)) + properties = self.graph.nodes[entity].get('properties', {}) + + return { + 'entity': entity, + 'properties': properties, + 'relations': neighbors + } + + def find_path(self, start, end): + """查找两个实体之间的路径""" + try: + path = nx.shortest_path(self.graph, start, end) + return path + except nx.NetworkXNoPath: + return None + +# 使用示例 +kg = KnowledgeGraph() +kg.add_entity("张三", "Person", {"age": 30, "job": "工程师"}) +kg.add_entity("ABC公司", "Company", {"industry": "科技"}) +kg.add_relation("张三", "ABC公司", "works_at") + +# 查询 +info = kg.query("张三") +``` + +### 2.3 分层记忆系统 + +```python +class HierarchicalMemory: + """分层记忆系统""" + + def __init__(self): + # 短期记忆（最近的对话） + self.short_term = [] + self.short_term_limit = 10 + + # 工作记忆（当前任务相关） + self.working_memory = {} + + # 长期记忆（重要信息） + self.long_term = [] + + def add_to_short_term(self, item): + """添加到短期记忆""" + self.short_term.append(item) + if len(self.short_term) > self.short_term_limit: + # 转移到长期记忆 + old_item = self.short_term.pop(0) + if self.is_important(old_item): + self.add_to_long_term(old_item) + + def add_to_working_memory(self, key, value): + """添加到工作记忆""" + self.working_memory[key] = value + + def add_to_long_term(self, item): + """添加到长期记忆""" + self.long_term.append(item) + + def is_important(self, item): + """判断信息是否重要""" + # 实现重要性判断逻辑 + return True + + def retrieve(self, query): + """检索相关记忆""" + results = [] + + # 从各层记忆中检索 + results.extend(self.search_short_term(query)) + results.extend(self.search_working_memory(query)) + results.extend(self.search_long_term(query)) + + return results +``` + +## 3. Agent 安全性 + +### 3.1 输入过滤 + +```python +import re +from typing import List + +class SecurityFilter: + """安全过滤器""" + + def __init__(self): + # 危险模式列表 + self.dangerous_patterns = [ + r'rm\s+-rf', + r'DROP\s+TABLE', + r'DELETE\s+FROM', + r'eval\s*\(', + r'exec\s*\(', + r'__import__', + ] + + def is_safe(self, input_text: str) -> bool: + """检查输入是否安全""" + # 检查危险模式 + for pattern in self.dangerous_patterns: + if re.search(pattern, input_text, re.IGNORECASE): + return False + + # 检查长度 + if len(input_text) > 10000: + return False + + return True + + def sanitize(self, input_text: str) -> str: + """清理输入""" + # 移除特殊字符 + cleaned = re.sub(r'[<>\"\'\\]', '', input_text) + + # 限制长度 + cleaned = cleaned[:10000] + + return cleaned + +# 使用示例 +security_filter = SecurityFilter() + +def safe_agent_run(user_input): + if not security_filter.is_safe(user_input): + return "输入包含不安全内容" + + cleaned_input = security_filter.sanitize(user_input) + return agent.run(cleaned_input) +``` + +### 3.2 权限管理 + +```python +from enum import Enum +from typing import Set + +class Permission(Enum): + READ = "read" + WRITE = "write" + EXECUTE = "execute" + ADMIN = "admin" + +class PermissionManager: + """权限管理器""" + + def __init__(self): + self.user_permissions: Dict[str, Set[Permission]] = {} + self.tool_requirements: Dict[str, Set[Permission]] = {} + + def grant_permission(self, user: str, permission: Permission): + """授予权限""" + if user not in self.user_permissions: + self.user_permissions[user] = set() + self.user_permissions[user].add(permission) + + def set_tool_requirement(self, tool: str, required: Set[Permission]): + """设置工具所需权限""" + self.tool_requirements[tool] = required + + def can_use_tool(self, user: str, tool: str) -> bool: + """检查用户是否可以使用工具""" + user_perms = self.user_permissions.get(user, set()) + required_perms = self.tool_requirements.get(tool, set()) + + return required_perms.issubset(user_perms) + +# 使用示例 +pm = PermissionManager() +pm.grant_permission("user1", Permission.READ) +pm.grant_permission("admin", Permission.ADMIN) +pm.set_tool_requirement("DeleteFile", {Permission.WRITE, Permission.ADMIN}) + +if pm.can_use_tool("user1", "DeleteFile"): + # 执行操作 + pass +``` + +### 3.3 审计日志 + +```python +import logging +from datetime import datetime +import json + +class AuditLogger: + """审计日志""" + + def __init__(self, log_file="audit.log"): + self.logger = logging.getLogger('audit') + self.logger.setLevel(logging.INFO) + + handler = logging.FileHandler(log_file) + handler.setFormatter( + logging.Formatter('%(message)s') + ) + self.logger.addHandler(handler) + + def log_action(self, user, action, details, status): + """记录操作""" + log_entry = { + 'timestamp': datetime.now().isoformat(), + 'user': user, + 'action': action, + 'details': details, + 'status': status + } + self.logger.info(json.dumps(log_entry, ensure_ascii=False)) + + def log_tool_use(self, user, tool, input_data, output_data): + """记录工具使用""" + self.log_action( + user=user, + action=f"use_tool:{tool}", + details={ + 'input': input_data, + 'output': output_data + }, + status='success' + ) + +# 使用示例 +audit = AuditLogger() +audit.log_tool_use("user1", "FileDelete", "file.txt", "deleted") +``` + +## 4. 评估与测试 + +### 4.1 自动化评估 + +```python +class AgentEvaluator: + """Agent 评估器""" + + def __init__(self, agent): + self.agent = agent + + def evaluate_accuracy(self, test_cases): + """评估准确性""" + correct = 0 + total = len(test_cases) + + for case in test_cases: + input_text = case['input'] + expected = case['expected'] + + result = self.agent.run(input_text) + if self.compare_results(result, expected): + correct += 1 + + accuracy = correct / total + return accuracy + + def evaluate_latency(self, queries, iterations=10): + """评估延迟""" + import time + + times = [] + for _ in range(iterations): + for query in queries: + start = time.time() + self.agent.run(query) + end = time.time() + times.append(end - start) + + return { + 'average': sum(times) / len(times), + 'min': min(times), + 'max': max(times), + 'p95': sorted(times)[int(len(times) * 0.95)] + } + + def evaluate_tool_selection(self, test_cases): + """评估工具选择""" + correct_selections = 0 + + for case in test_cases: + query = case['query'] + expected_tool = case['expected_tool'] + + # 获取 Agent 使用的工具 + used_tools = self.get_used_tools(query) + + if expected_tool in used_tools: + correct_selections += 1 + + accuracy = correct_selections / len(test_cases) + return accuracy + + def compare_results(self, result, expected): + """比较结果""" + # 实现比较逻辑 + return result.strip().lower() == expected.strip().lower() + + def get_used_tools(self, query): + """获取使用的工具""" + # 实现获取工具逻辑 + return [] + +# 使用示例 +evaluator = AgentEvaluator(agent) + +test_cases = [ + {'input': '现在几点？', 'expected': '包含时间信息'}, + {'input': '2+3等于多少？', 'expected': '5'}, +] + +accuracy = evaluator.evaluate_accuracy(test_cases) +print(f"准确率：{accuracy * 100:.2f}%") +``` + +### 4.2 A/B 测试 + +```python +class ABTester: + """A/B 测试""" + + def __init__(self, agent_a, agent_b): + self.agent_a = agent_a + self.agent_b = agent_b + self.results_a = [] + self.results_b = [] + + def run_test(self, queries): + """运行 A/B 测试""" + for query in queries: + # 测试 Agent A + result_a = self.agent_a.run(query) + self.results_a.append({ + 'query': query, + 'result': result_a, + 'timestamp': datetime.now() + }) + + # 测试 Agent B + result_b = self.agent_b.run(query) + self.results_b.append({ + 'query': query, + 'result': result_b, + 'timestamp': datetime.now() + }) + + def compare_performance(self): + """比较性能""" + # 实现性能比较逻辑 + return { + 'agent_a_wins': 0, + 'agent_b_wins': 0, + 'ties': 0 + } +``` + +## 5. 高级工具集成 + +### 5.1 API 集成 + +```python +import requests + +class APITool(BaseTool): + """API 工具基类""" + + def __init__(self, api_url, api_key): + self.api_url = api_url + self.api_key = api_key + + def call_api(self, endpoint, params=None): + """调用 API""" + headers = { + 'Authorization': f'Bearer {self.api_key}', + 'Content-Type': 'application/json' + } + + response = requests.post( + f"{self.api_url}/{endpoint}", + json=params, + headers=headers, + timeout=30 + ) + + if response.status_code == 200: + return response.json() + else: + raise Exception(f"API 调用失败：{response.status_code}") +``` + +### 5.2 数据库集成 + +```python +import sqlite3 + +class DatabaseTool(BaseTool): + """数据库工具""" + + def __init__(self, db_path): + self.db_path = db_path + + def query(self, sql, params=None): + """执行查询""" + conn = sqlite3.connect(self.db_path) + cursor = conn.cursor() + + try: + cursor.execute(sql, params or []) + results = cursor.fetchall() + return results + finally: + conn.close() + + def execute(self, sql, params=None): + """执行更新""" + conn = sqlite3.connect(self.db_path) + cursor = conn.cursor() + + try: + cursor.execute(sql, params or []) + conn.commit() + return cursor.rowcount + finally: + conn.close() +``` + +## 总结 + +本章介绍了 Agent 开发的高级主题： + +- ✅ 多 Agent 系统设计与协作 +- ✅ 长期记忆和知识管理 +- ✅ 安全性和权限控制 +- ✅ 评估与测试方法 +- ✅ 高级工具集成 + +## 下一步 + +- 查看 [常见问题](07-troubleshooting.md) 解决开发中的问题 +- 参考 [资源列表](08-resources.md) 继续深入学习 +- 实践项目，应用所学知识 diff --git a/tutorials/07-troubleshooting.md b/tutorials/07-troubleshooting.md new file mode 100644 index 0000000..4379660 --- /dev/null +++ b/tutorials/07-troubleshooting.md @@ -0,0 +1,638 @@ +# 常见问题与故障排除 + +解决 Agent 开发和使用过程中遇到的常见问题。 + +## 1. 安装和配置问题 + +### Q1: 安装 LangChain 失败 + +**问题描述：** +```bash +pip install langchain +ERROR: Could not find a version that satisfies the requirement... +``` + +**解决方案：** + +1. 升级 pip： +```bash +python -m pip install --upgrade pip +``` + +2. 使用国内镜像源： +```bash +pip install langchain -i https://pypi.tuna.tsinghua.edu.cn/simple +``` + +3. 检查 Python 版本（需要 3.8+）： +```bash +python --version +``` + +### Q2: API 密钥配置不生效 + +**问题描述：** +设置了环境变量但 Agent 仍然报告找不到 API 密钥。 + +**解决方案：** + +1. 确认 `.env` 文件在正确位置： +```python +# 确保在代码开始处加载 +from dotenv import load_dotenv +load_dotenv() # 默认加载当前目录的 .env + +# 或指定路径 +load_dotenv('.env') +load_dotenv('/path/to/.env') +``` + +2. 检查环境变量是否加载： +```python +import os +print(os.getenv('OPENAI_API_KEY')) +``` + +3. 直接在代码中设置（仅用于测试）： +```python +import os +os.environ['OPENAI_API_KEY'] = 'your-key-here' +``` + +### Q3: 导入错误 + +**问题描述：** +```python +ImportError: cannot import name 'initialize_agent' from 'langchain.agents' +``` + +**解决方案：** + +1. 更新 LangChain 到最新版本： +```bash +pip install --upgrade langchain +``` + +2. 检查导入路径： +```python +# 旧版本 +from langchain.agents import initialize_agent + +# 新版本可能变更了路径 +from langchain.agents import AgentExecutor +``` + +3. 查看官方文档确认最新 API。 + +## 2. Agent 行为问题 + +### Q4: Agent 不调用工具 + +**问题描述：** +Agent 直接回答问题而不使用提供的工具。 + +**可能原因和解决方案：** + +1. **工具描述不够清晰** + +```python +# ❌ 描述模糊 +Tool( + name="Tool1", + func=my_func, + description="一个工具" +) + +# ✅ 描述清晰 +Tool( + name="GetWeather", + func=get_weather, + description="获取指定城市的天气信息。输入应该是城市名称，例如'北京'或'上海'。" +) +``` + +2. **问题不需要工具** + +```python +# LLM 可以直接回答的问题不会调用工具 +# 确保问题确实需要工具才能回答 +query = "现在北京的天气如何？" # 需要工具 +# 而不是： +query = "什么是天气？" # 不需要工具 +``` + +3. **工具太多导致选择困难** + +```python +# 限制工具数量（建议少于 10 个） +tools = tools[:5] # 只使用前 5 个工具 +``` + +4. **使用 verbose 模式调试** + +```python +agent = initialize_agent( + tools=tools, + llm=llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True # 查看 Agent 的思考过程 +) +``` + +### Q5: Agent 陷入无限循环 + +**问题描述：** +Agent 重复执行相同的操作，无法完成任务。 + +**解决方案：** + +1. **限制最大迭代次数** + +```python +from langchain.agents import AgentExecutor + +agent_executor = AgentExecutor( + agent=agent, + tools=tools, + max_iterations=5, # 限制迭代次数 + verbose=True +) +``` + +2. **设置超时时间** + +```python +agent_executor = AgentExecutor( + agent=agent, + tools=tools, + max_execution_time=30, # 30秒超时 + verbose=True +) +``` + +3. **检查工具的返回值** + +```python +def my_tool(input_str): + """确保返回明确的结果""" + result = process(input_str) + + # ❌ 返回模糊 + return "处理完成" + + # ✅ 返回具体信息 + return f"处理完成，结果：{result}" +``` + +### Q6: Agent 输出格式错误 + +**问题描述：** +Agent 的输出格式不符合预期。 + +**解决方案：** + +1. **在提示中明确要求格式** + +```python +format_prompt = """ +请按照以下格式回答： + +标题：xxx +内容：xxx +结论：xxx +""" + +agent.run(f"{format_prompt}\n\n问题：{query}") +``` + +2. **使用输出解析器** + +```python +from langchain.output_parsers import StructuredOutputParser, ResponseSchema + +response_schemas = [ + ResponseSchema(name="answer", description="答案"), + ResponseSchema(name="confidence", description="置信度"), +] + +parser = StructuredOutputParser.from_response_schemas(response_schemas) +format_instructions = parser.get_format_instructions() + +# 在提示中包含格式说明 +prompt = f"{query}\n\n{format_instructions}" +``` + +3. **后处理输出** + +```python +def clean_output(output): + """清理和格式化输出""" + # 移除多余空白 + output = output.strip() + + # 统一换行符 + output = output.replace('\r\n', '\n') + + # 其他清理逻辑 + return output + +result = agent.run(query) +cleaned_result = clean_output(result) +``` + +## 3. 性能问题 + +### Q7: Agent 响应太慢 + +**问题描述：** +Agent 执行任务耗时很长。 + +**优化方案：** + +1. **使用更快的模型** + +```python +# 使用 GPT-3.5 而不是 GPT-4 +llm = ChatOpenAI(model="gpt-3.5-turbo") # 更快 +# llm = ChatOpenAI(model="gpt-4") # 更准确但更慢 +``` + +2. **减少上下文长度** + +```python +from langchain.memory import ConversationBufferWindowMemory + +# 只保留最近几轮对话 +memory = ConversationBufferWindowMemory(k=3) +``` + +3. **优化工具执行** + +```python +import functools + +@functools.lru_cache(maxsize=100) +def cached_tool(input_str): + """缓存工具结果""" + return expensive_operation(input_str) +``` + +4. **并行执行** + +```python +import asyncio + +async def parallel_agent_calls(): + tasks = [ + agent1.arun(query1), + agent2.arun(query2), + ] + results = await asyncio.gather(*tasks) + return results +``` + +### Q8: 内存占用过高 + +**问题描述：** +Agent 运行时内存占用不断增长。 + +**解决方案：** + +1. **限制记忆大小** + +```python +from langchain.memory import ConversationSummaryMemory + +# 使用摘要记忆而不是完整记忆 +memory = ConversationSummaryMemory(llm=llm) +``` + +2. **定期清理** + +```python +# 每 N 次交互后清理记忆 +interaction_count = 0 + +def agent_run_with_cleanup(query): + global interaction_count + result = agent.run(query) + + interaction_count += 1 + if interaction_count > 10: + memory.clear() + interaction_count = 0 + + return result +``` + +3. **使用流式处理** + +```python +from langchain.callbacks import StreamingStdOutCallbackHandler + +llm = ChatOpenAI( + streaming=True, + callbacks=[StreamingStdOutCallbackHandler()] +) +``` + +## 4. API 相关问题 + +### Q9: API 调用超时 + +**问题描述：** +``` +timeout: The read operation timed out +``` + +**解决方案：** + +1. **增加超时时间** + +```python +llm = ChatOpenAI( + request_timeout=60 # 60秒超时 +) +``` + +2. **实现重试机制** + +```python +from tenacity import retry, stop_after_attempt, wait_exponential + +@retry( + stop=stop_after_attempt(3), + wait=wait_exponential(multiplier=1, min=4, max=10) +) +def call_agent_with_retry(query): + return agent.run(query) +``` + +3. **检查网络连接** + +```python +import requests + +def check_api_connectivity(): + try: + response = requests.get('https://api.openai.com', timeout=5) + return True + except: + return False + +if check_api_connectivity(): + result = agent.run(query) +else: + print("API 无法访问") +``` + +### Q10: API 配额超限 + +**问题描述：** +``` +RateLimitError: Rate limit reached +``` + +**解决方案：** + +1. **实现速率限制** + +```python +import time +from functools import wraps + +def rate_limit(max_per_minute): + min_interval = 60.0 / max_per_minute + last_called = [0.0] + + def decorator(func): + @wraps(func) + def wrapper(*args, **kwargs): + elapsed = time.time() - last_called[0] + left_to_wait = min_interval - elapsed + + if left_to_wait > 0: + time.sleep(left_to_wait) + + result = func(*args, **kwargs) + last_called[0] = time.time() + return result + return wrapper + return decorator + +@rate_limit(max_per_minute=20) +def call_agent(query): + return agent.run(query) +``` + +2. **使用队列管理请求** + +```python +from queue import Queue +import threading + +class RequestQueue: + def __init__(self, max_per_minute): + self.queue = Queue() + self.max_per_minute = max_per_minute + self.start_worker() + + def start_worker(self): + def worker(): + while True: + query, callback = self.queue.get() + result = agent.run(query) + callback(result) + time.sleep(60 / self.max_per_minute) + + thread = threading.Thread(target=worker, daemon=True) + thread.start() + + def submit(self, query, callback): + self.queue.put((query, callback)) +``` + +## 5. 工具相关问题 + +### Q11: 自定义工具不工作 + +**问题描述：** +自定义的工具无法被 Agent 正确调用。 + +**检查清单：** + +1. **确保工具描述清晰** + +```python +Tool( + name="MyTool", + func=my_function, + description=""" + 清晰描述工具的功能。 + + 输入格式：详细说明输入应该是什么 + 输出格式：说明会返回什么 + 使用场景：什么情况下应该使用这个工具 + """ +) +``` + +2. **检查函数签名** + +```python +# ✅ 正确：接受字符串参数，返回字符串 +def my_tool(input_str: str) -> str: + return f"处理结果：{input_str}" + +# ❌ 错误：参数类型不匹配 +def my_tool(input_dict: dict) -> dict: + return {"result": "data"} +``` + +3. **添加错误处理** + +```python +def robust_tool(input_str: str) -> str: + try: + result = process(input_str) + return f"成功：{result}" + except Exception as e: + return f"错误：{str(e)}" +``` + +### Q12: 工具返回结果但 Agent 无法理解 + +**解决方案：** + +1. **返回结构化信息** + +```python +def better_tool(query): + result = search(query) + + # ❌ 返回原始数据 + return result + + # ✅ 返回易于理解的文本 + return f"找到 {len(result)} 个结果。最相关的是：{result[0]}" +``` + +2. **添加上下文信息** + +```python +def contextual_tool(query): + result = process(query) + + return f""" + 查询：{query} + 结果：{result} + 状态：成功 + 建议：基于此结果，您可以... + """ +``` + +## 6. 调试技巧 + +### 技巧 1: 使用详细日志 + +```python +import logging + +logging.basicConfig(level=logging.DEBUG) +logger = logging.getLogger(__name__) + +# 在关键位置添加日志 +logger.debug(f"输入：{user_input}") +logger.debug(f"工具选择：{selected_tool}") +logger.debug(f"工具输出：{tool_output}") +``` + +### 技巧 2: 逐步执行 + +```python +# 分步测试 +print("步骤 1: 测试工具") +tool_result = tool.run("test input") +print(f"工具结果：{tool_result}") + +print("步骤 2: 测试 Agent") +agent_result = agent.run("test query") +print(f"Agent 结果：{agent_result}") +``` + +### 技巧 3: 使用断点调试 + +```python +import pdb + +def debug_tool(input_str): + # 设置断点 + pdb.set_trace() + + result = process(input_str) + return result +``` + +### 技巧 4: 记录中间结果 + +```python +class DebugAgent: + def __init__(self, agent): + self.agent = agent + self.history = [] + + def run(self, query): + self.history.append({ + 'query': query, + 'timestamp': datetime.now() + }) + + result = self.agent.run(query) + + self.history[-1]['result'] = result + return result + + def print_history(self): + for item in self.history: + print(f"Query: {item['query']}") + print(f"Result: {item['result']}") + print("---") +``` + +## 常见错误速查表 + +| 错误信息 | 可能原因 | 解决方案 | +|---------|---------|---------| +| `API key not found` | 未设置 API 密钥 | 检查环境变量配置 | +| `Rate limit exceeded` | API 调用过于频繁 | 实现速率限制 | +| `Timeout` | 请求超时 | 增加超时时间或优化操作 | +| `Parsing error` | 输出格式错误 | 优化提示词或添加解析器 | +| `Tool not found` | 工具名称错误 | 检查工具名称拼写 | +| `Max iterations` | 迭代次数超限 | 检查任务逻辑或增加限制 | + +## 获取帮助 + +如果问题仍未解决： + +1. **查看官方文档** + - [LangChain 文档](https://python.langchain.com/) + - [OpenAI 文档](https://platform.openai.com/docs) + +2. **搜索 GitHub Issues** + - [LangChain Issues](https://github.com/langchain-ai/langchain/issues) + +3. **社区支持** + - Stack Overflow + - Discord 社区 + - GitHub Discussions + +4. **提交 Issue** + - 提供详细的错误信息 + - 包含最小可复现示例 + - 说明环境信息 + +## 下一步 + +- 查看 [资源列表](08-resources.md) 获取更多学习资料 +- 回顾 [最佳实践](05-best-practices.md) 避免常见问题 +- 参考 [实践案例](04-practical-examples.md) 学习正确用法 diff --git a/tutorials/08-resources.md b/tutorials/08-resources.md new file mode 100644 index 0000000..e048115 --- /dev/null +++ b/tutorials/08-resources.md @@ -0,0 +1,525 @@ +# 资源与参考 + +精选的 Agent 学习资源、工具和社区链接。 + +## 1. 开发框架 + +### LangChain + +**简介：** 最流行的 Agent 开发框架，功能丰富且社区活跃。 + +- 🌐 官网：https://www.langchain.com/ +- 📚 文档：https://python.langchain.com/docs/get_started/introduction +- 💻 GitHub：https://github.com/langchain-ai/langchain +- ⭐ Stars: 80k+ + +**特点：** +- 完整的 Agent 开发工具链 +- 丰富的内置工具和集成 +- 支持多种 LLM +- 活跃的社区支持 + +**适合场景：** +- 快速原型开发 +- 生产环境应用 +- 复杂 Agent 系统 + +### LlamaIndex + +**简介：** 专注于数据索引和检索的框架。 + +- 🌐 官网：https://www.llamaindex.ai/ +- 📚 文档：https://docs.llamaindex.ai/ +- 💻 GitHub：https://github.com/run-llama/llama_index +- ⭐ Stars: 30k+ + +**特点：** +- 强大的数据索引能力 +- 优秀的文档检索 +- 知识库集成 + +**适合场景：** +- 文档问答系统 +- 知识库应用 +- RAG（检索增强生成） + +### AutoGPT + +**简介：** 自主 Agent 系统，能够自主完成复杂任务。 + +- 💻 GitHub：https://github.com/Significant-Gravitas/AutoGPT +- 📚 文档：https://docs.agpt.co/ +- ⭐ Stars: 160k+ + +**特点：** +- 高度自主性 +- 任务规划能力 +- 可扩展插件系统 + +**适合场景：** +- 自动化任务 +- 长期运行的 Agent +- 实验性项目 + +### Semantic Kernel + +**简介：** 微软开发的轻量级 Agent 框架。 + +- 💻 GitHub：https://github.com/microsoft/semantic-kernel +- 📚 文档：https://learn.microsoft.com/en-us/semantic-kernel/ +- ⭐ Stars: 18k+ + +**特点：** +- 企业级设计 +- 多语言支持（C#, Python, Java） +- 与 Azure 深度集成 + +**适合场景：** +- 企业应用 +- .NET 生态系统 +- Azure 平台 + +### Haystack + +**简介：** 面向 NLP 和搜索的框架。 + +- 💻 GitHub：https://github.com/deepset-ai/haystack +- 📚 文档：https://haystack.deepset.ai/ +- ⭐ Stars: 13k+ + +**特点：** +- 专注于搜索和问答 +- 支持多种检索方法 +- 生产就绪 + +**适合场景：** +- 搜索引擎 +- 问答系统 +- 文档处理 + +## 2. 大语言模型服务 + +### OpenAI + +- 🌐 官网：https://openai.com/ +- 📚 API 文档：https://platform.openai.com/docs/ +- 💰 定价：https://openai.com/pricing + +**主要模型：** +- GPT-4：最强大的模型 +- GPT-3.5-turbo：性价比高 +- GPT-4-turbo：长上下文支持 + +### Anthropic Claude + +- 🌐 官网：https://www.anthropic.com/ +- 📚 文档：https://docs.anthropic.com/ +- 💰 定价：https://www.anthropic.com/pricing + +**特点：** +- 大上下文窗口（100k+ tokens） +- 优秀的代码能力 +- Constitutional AI + +### Google Gemini + +- 🌐 官网：https://deepmind.google/technologies/gemini/ +- 📚 文档：https://ai.google.dev/ + +**特点：** +- 多模态能力 +- 与 Google 服务集成 +- 免费配额 + +### 开源模型 + +**LLaMA 2** +- 💻 GitHub：https://github.com/facebookresearch/llama +- Meta 开源的大语言模型 + +**Mistral** +- 🌐 官网：https://mistral.ai/ +- 高性能开源模型 + +**Qwen** +- 💻 GitHub：https://github.com/QwenLM/Qwen +- 阿里云开源的中文优化模型 + +## 3. 向量数据库 + +### Pinecone + +- 🌐 官网：https://www.pinecone.io/ +- 云端向量数据库 +- 易于使用，性能优秀 + +### Weaviate + +- 🌐 官网：https://weaviate.io/ +- 💻 GitHub：https://github.com/weaviate/weaviate +- 开源，支持混合搜索 + +### Milvus + +- 🌐 官网：https://milvus.io/ +- 💻 GitHub：https://github.com/milvus-io/milvus +- 高性能，云原生 + +### Chroma + +- 🌐 官网：https://www.trychroma.com/ +- 💻 GitHub：https://github.com/chroma-core/chroma +- 轻量级，适合快速原型 + +### Qdrant + +- 🌐 官网：https://qdrant.tech/ +- 💻 GitHub：https://github.com/qdrant/qdrant +- Rust 编写，性能出色 + +## 4. 工具和集成 + +### API 工具 + +**Requests** +```bash +pip install requests +``` +- HTTP 请求库 +- 用于 API 调用 + +**httpx** +```bash +pip install httpx +``` +- 异步 HTTP 客户端 +- 支持 HTTP/2 + +### 数据处理 + +**Pandas** +```bash +pip install pandas +``` +- 数据分析和处理 +- 必备的数据工具 + +**NumPy** +```bash +pip install numpy +``` +- 数值计算 +- 数组操作 + +### 可视化 + +**Matplotlib** +```bash +pip install matplotlib +``` +- 基础绘图库 + +**Plotly** +```bash +pip install plotly +``` +- 交互式图表 + +**Streamlit** +```bash +pip install streamlit +``` +- 快速构建 Web 应用 +- 适合演示和原型 + +### 网页抓取 + +**BeautifulSoup** +```bash +pip install beautifulsoup4 +``` +- HTML 解析 +- 网页数据提取 + +**Selenium** +```bash +pip install selenium +``` +- 浏览器自动化 +- 动态内容抓取 + +## 5. 学习资源 + +### 在线课程 + +**DeepLearning.AI** +- 课程：ChatGPT Prompt Engineering for Developers +- 链接：https://www.deeplearning.ai/short-courses/ + +**Coursera** +- 课程：Generative AI with Large Language Models +- 链接：https://www.coursera.org/ + +**Udemy** +- 多个 LangChain 和 Agent 相关课程 +- 链接：https://www.udemy.com/ + +### 书籍推荐 + +**《动手学大语言模型应用开发》** +- 实践导向 +- 案例丰富 + +**《Large Language Models》** +- 理论深入 +- 英文原版 + +**《Hands-On Large Language Models》** +- 实战指南 +- 代码示例丰富 + +### 技术博客 + +**LangChain Blog** +- https://blog.langchain.dev/ +- 最新功能和最佳实践 + +**OpenAI Blog** +- https://openai.com/blog/ +- AI 前沿动态 + +**Hugging Face Blog** +- https://huggingface.co/blog +- 模型和工具介绍 + +### 视频教程 + +**YouTube 频道推荐：** + +1. **AI Jason** + - LangChain 教程 + - 实战案例 + +2. **Sam Witteveen** + - 深入的技术讲解 + - 新功能介绍 + +3. **AI Anytime** + - Agent 应用案例 + - 工具使用技巧 + +## 6. 研究论文 + +### 经典论文 + +**ReAct: Synergizing Reasoning and Acting in Language Models** +- 论文：https://arxiv.org/abs/2210.03629 +- ReAct 模式的原始论文 + +**Toolformer: Language Models Can Teach Themselves to Use Tools** +- 论文：https://arxiv.org/abs/2302.04761 +- 工具使用的理论基础 + +**Chain-of-Thought Prompting Elicits Reasoning in Large Language Models** +- 论文：https://arxiv.org/abs/2201.11903 +- 思维链技术 + +**A Survey on Large Language Model based Autonomous Agents** +- 论文：https://arxiv.org/abs/2308.11432 +- Agent 领域综述 + +### 论文集合 + +**LLM-Agent-Paper-List** +- GitHub：https://github.com/Paitesanshi/LLM-Agent-Survey +- Agent 相关论文汇总 + +## 7. 社区和论坛 + +### GitHub Discussions + +**LangChain Discussions** +- https://github.com/langchain-ai/langchain/discussions +- 技术讨论和问答 + +### Discord 服务器 + +**LangChain Discord** +- 活跃的开发者社区 +- 实时技术支持 + +**OpenAI Discord** +- OpenAI 官方社区 +- API 使用讨论 + +### Reddit + +**r/LangChain** +- https://www.reddit.com/r/LangChain/ +- 经验分享和讨论 + +**r/MachineLearning** +- https://www.reddit.com/r/MachineLearning/ +- 机器学习前沿 + +### 中文社区 + +**思知 AI 社区** +- Agent 技术讨论 +- 中文资源分享 + +**CSDN** +- 技术博客 +- 代码分享 + +**知乎** +- 深度文章 +- 经验交流 + +## 8. 开发工具 + +### IDE 和编辑器 + +**VS Code** +- 插件：Python, Jupyter +- 强大的扩展生态 + +**PyCharm** +- 专业的 Python IDE +- 调试功能强大 + +**Jupyter Notebook** +- 交互式开发 +- 适合实验和演示 + +### 版本控制 + +**Git** +- 代码版本管理 +- 必备工具 + +**GitHub** +- 代码托管 +- 协作开发 + +### 项目管理 + +**Poetry** +- Python 包管理 +- 依赖管理 + +**Docker** +- 容器化部署 +- 环境一致性 + +## 9. 示例项目 + +### 开源项目 + +**LangChain Templates** +- GitHub：https://github.com/langchain-ai/langchain/tree/master/templates +- 官方模板项目 + +**Awesome LangChain** +- GitHub：https://github.com/kyrolabs/awesome-langchain +- 精选项目列表 + +**Agent Examples** +- 本仓库的 examples 目录 +- 实用代码示例 + +## 10. 持续学习建议 + +### 学习路径 + +1. **基础阶段** + - 学习 Python 基础 + - 理解 LLM 原理 + - 掌握基本 Prompt 技巧 + +2. **进阶阶段** + - 学习 LangChain 框架 + - 实现简单 Agent + - 集成各种工具 + +3. **高级阶段** + - 多 Agent 系统 + - 性能优化 + - 生产部署 + +### 实践建议 + +1. **动手实践** + - 从简单项目开始 + - 逐步增加复杂度 + - 记录经验教训 + +2. **阅读代码** + - 研究开源项目 + - 学习最佳实践 + - 理解设计模式 + +3. **参与社区** + - 提问和回答 + - 分享经验 + - 贡献代码 + +4. **关注前沿** + - 跟踪最新研究 + - 尝试新技术 + - 参加技术会议 + +## 11. 常用命令速查 + +```bash +# 安装 LangChain +pip install langchain openai + +# 更新到最新版本 +pip install --upgrade langchain + +# 安装额外功能 +pip install langchain[all] + +# 安装向量数据库 +pip install chromadb +pip install pinecone-client + +# 安装工具 +pip install google-search-results +pip install wikipedia + +# 开发工具 +pip install python-dotenv +pip install jupyter + +# 运行示例 +python examples/simple_agent.py + +# 启动 Jupyter +jupyter notebook +``` + +## 总结 + +本章提供了丰富的学习资源： + +- ✅ 主流开发框架 +- ✅ LLM 服务提供商 +- ✅ 向量数据库选择 +- ✅ 实用工具集合 +- ✅ 学习资源推荐 +- ✅ 社区和论坛 +- ✅ 开源项目参考 + +**祝您学习愉快！不断实践，持续进步！** 🚀 + +--- + +## 贡献 + +欢迎补充更多有用的资源！请通过 Pull Request 或 Issue 提交。 + +## 联系方式 + +如有问题或建议，请在 GitHub 上提 Issue。