alihan/agents-course
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

translate rest sections

Browse Source
This commit is contained in:
JiamingHuangHJM
2025-02-26 10:08:13 +01:00
parent cac845aff5
commit 3cae6fcc7c
6 changed files with 190 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
units/zh-CN/unit2/introduction.mdx
View File

@@ -1,37 +1,38 @@
# Introduction to Agentic Frameworks
# 智能体框架介绍
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit2/thumbnail.jpg" alt="Thumbnail"/>
Welcome to this second unit, where **we'll explore different agentic frameworks** that can be used to build powerful agentic applications.
欢迎来到第二单元，在这里**我们将探索不同的智能体框架（agentic frameworks）**，这些框架可用于构建强大的智能体应用。
We will study:
我们将学习：
- In Unit 2.1: [smolagents](https://huggingface.co/docs/smolagents/en/index)
- In Unit 2.2: [LlamaIndex](https://www.llamaindex.ai/)
- In Unit 2.3: [LangGraph](https://www.langchain.com/langgraph)
- 在单元 2.1：[smolagents](https://huggingface.co/docs/smolagents/en/index)
- 在单元 2.2：[LlamaIndex](https://www.llamaindex.ai/)
- 在单元 2.3：[LangGraph](https://www.langchain.com/langgraph)
Let's dive in! 🕵
让我们开始吧！🕵
## When to Use an Agentic Framework
## 何时使用智能体框架
An agentic framework is **not always needed when building an application around LLMs**. They provide flexibility in the workflow to efficiently solve a specific task, but they're not always necessary.
**构建围绕大语言模型（LLMs）的应用时，并不总是需要智能体框架**。它们在工作流中提供了灵活性，可以高效地解决特定任务，但并非总是必需的。
Sometimes, **predefined workflows are sufficient** to fulfill user requests, and there is no real need for an agentic framework. If the approach to build an agent is simple, like a chain of prompts, using plain code may be enough. The advantage is that the developer will have **full control and understanding of their system without abstractions**.
有时，**预定义的工作流足以满足用户请求**，并且没有真正需要智能体框架。如果构建智能体的方法很简单，比如一系列提示，使用纯代码可能就足够了。优势在于开发者将**完全控制和理解他们的系统，没有抽象层**。
However, when the workflow becomes more complex, such as letting an LLM call functions or using multiple agents, these abstractions start to become helpful.
然而，当工作流变得更加复杂时，例如让大语言模型调用函数或使用多个智能体，这些抽象开始变得有用。
Considering these ideas, we can already identify the need for some features:
考虑到这些想法，我们已经可以确定对一些功能的需求：
* An *LLM engine* that powers the system.
* A *list of tools* the agent can access.
* A *parser* for extracting tool calls from the LLM output.
* A *system prompt* synced with the parser.
* A *memory system*.
* *Error logging and retry mechanisms* to control LLM mistakes.
We'll explore how these topics are resolved in various frameworks, including `smolagents`, `LlamaIndex`, and `LangGraph`.
* 一个驱动系统的*大语言模型引擎*。
* 智能体可以访问的*工具列表*。
* 用于从大语言模型输出中提取工具调用的*解析器*。
* 与解析器同步的*系统提示*。
* 一个*记忆系统*。
* *错误日志和重试机制*以控制大语言模型的错误。
## Agentic Frameworks Units
我们将探讨这些主题在各种框架中如何解决，包括 `smolagents`、`LlamaIndex` 和 `LangGraph`。
| Framework | Description | Unit Author |
## 智能体框架单元
| 框架 | 描述 | 单元作者 |
|------------|----------------|----------------|
| [smolagents](./smolagents/introduction) | Agents framework developed by Hugging Face. | Sergio Paniego - [HF](https://huggingface.co/sergiopaniego) - [X](https://x.com/sergiopaniego) - [Linkedin](https://www.linkedin.com/in/sergio-paniego-blanco) |
| [smolagents](./smolagents/introduction) | 由 Hugging Face 开发的智能体框架。 | Sergio Paniego - [HF](https://huggingface.co/sergiopaniego) - [X](https://x.com/sergiopaniego) - [Linkedin](https://www.linkedin.com/in/sergio-paniego-blanco) |

12
units/zh-CN/unit2/smolagents/conclusion.mdx
View File

@@ -1,11 +1,11 @@
# Conclusion
# 结论
Congratulations on finishing the `smolagents` module of this second Unit 🥳
恭喜你完成了第二单元的 `smolagents` 模块 🥳
You’ve just mastered the fundamentals of `smolagents` and you’ve built your own Agent! Now that you have skills in `smolagents`, you can now start to create Agents that will solve tasks you're interested about.
你刚刚掌握了 `smolagents` 的基础知识，并且构建了自己的智能体！现在你已经具备了 `smolagents` 的技能，你可以开始创建能够解决你感兴趣任务的智能体。
In the next module, you're going to learn **how to build Agents with LlamaIndex**.
在下一个模块中，你将学习**如何使用 LlamaIndex 构建智能体（Agents）**。
Finally, we would love **to hear what you think of the course and how we can improve it**. If you have some feedback then, please 👉 [fill this form](https://docs.google.com/forms/d/e/1FAIpQLSe9VaONn0eglax0uTwi29rIn4tM7H2sYmmybmG5jJNlE5v0xA/viewform?usp=dialog)
最后，我们非常想**听听你对这门课程的看法以及我们如何改进它**。如果你有任何反馈，请👉 [填写这个表格](https://docs.google.com/forms/d/e/1FAIpQLSe9VaONn0eglax0uTwi29rIn4tM7H2sYmmybmG5jJNlE5v0xA/viewform?usp=dialog)
### Keep Learning, stay awesome 🤗
### 继续学习，保持优秀 🤗

22
units/zh-CN/unit2/smolagents/final_quiz.mdx
View File

@@ -1,19 +1,19 @@
# Exam Time!
# 测验时间！
Well done on working through the material on `smolagents`! You've already achieved a lot. Now, it's time to put your knowledge to the test with a quiz. 🧠
恭喜你完成了 `smolagents` 的学习材料！你已经取得了很多成就。现在，是时候通过一个测验来测试你的知识了。🧠
## Instructions
## 说明
- The quiz consists of code questions.
- You will be given instructions to complete the code snippets.
- Read the instructions carefully and complete the code snippets accordingly.
- For each question, you will be given the result and some feedback.
- 测验由代码问题组成。
- 你将得到完成代码片段的指示。
- 仔细阅读指示并相应地完成代码片段。
- 对于每个问题，你将得到结果和一些反馈。
🧘 **This quiz is ungraded and uncertified**. It's about you understanding the `smolagents` library and knowing whether you should spend more time on the written material. In the coming units you'll put this knowledge to the test in use cases and projects.
🧘 **这个测验不计分也不提供证书**。这是关于你理解 `smolagents` 库，并了解你是否应该在书面材料上花更多时间。在接下来的单元中，你将在用例和项目中测试这些知识。
Let's get started!
让我们开始吧！
## Quiz 🚀
## 测验 🚀
<iframe
src="https://agents-course-unit2-smolagents-quiz.hf.space"
@@ -22,4 +22,4 @@ Let's get started!
height="450"
></iframe>
You can also access the quiz 👉 [here](https://huggingface.co/spaces/agents-course/unit2_smolagents_quiz)
你也可以点击👉 [这里](https://huggingface.co/spaces/agents-course/unit2_smolagents_quiz) 访问测验

66
units/zh-CN/unit2/smolagents/introduction.mdx
View File

@@ -1,69 +1,69 @@
# Introduction to `smolagents`
# `smolagents` 简介
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit2/smolagents/thumbnail.jpg" alt="Unit 2.1 Thumbnail"/>
Welcome to this module, where you'll learn **how to build effective agents** using the [`smolagents`](https://github.com/huggingface/smolagents) library, which provides a lightweight framework for creating capable AI agents.
欢迎来到本模块，在这里你将学习**如何使用 [`smolagents`](https://github.com/huggingface/smolagents) 库构建有效的智能体**，该库提供了一个轻量级框架，用于创建功能强大的AI智能体。
`smolagents` is a Hugging Face library; therefore, we would appreciate your support by **starring** the smolagents [`repository`](https://github.com/huggingface/smolagents) :
`smolagents` 是 Hugging Face 的一个库；因此，我们非常感谢您通过**加星标**的方式支持 smolagents [`仓库`](https://github.com/huggingface/smolagents)：
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit2/smolagents/star_smolagents.gif" alt="staring smolagents"/>
## Module Overview
## 模块概览
This module provides a comprehensive overview of key concepts and practical strategies for building intelligent agents using `smolagents`.
本模块提供了使用 `smolagents` 构建智能体的关键概念和实用策略的全面概述。
With so many open-source frameworks available, it's essential to understand the components and capabilities that make `smolagents` a useful option or to determine when another solution might be a better fit.
面对众多可用的开源框架，了解使 `smolagents` 成为有用选择的组件和功能，或确定何时另一种解决方案可能更合适，这一点至关重要。
We'll explore critical agent types, including code agents designed for software development tasks, tool calling agents for creating modular, function-driven workflows, and retrieval agents that access and synthesize information.
我们将探索关键的智能体类型，包括为软件开发任务设计的代码智能体（code agents），用于创建模块化、函数驱动工作流的工具调用智能体（tool calling agents），以及访问和综合信息的检索智能体（retrieval agents）。
Additionally, we'll cover the orchestration of multiple agents as well as the integration of vision capabilities and web browsing, which unlock new possibilities for dynamic and context-aware applications.
此外，我们还将讨论多个智能体的编排，以及视觉能力和网络浏览的集成，这为动态和上下文感知应用开辟了新的可能性。
In this unit, Alfred, the agent from Unit 1, makes his return. This time, he’s using the `smolagents` framework for his internal workings. Together, we’ll explore the key concepts behind this framework as Alfred tackles various tasks. Alfred is organizing a party at the Wayne Manor while the Wayne family 🦇 is away, and he has plenty to do. Join us as we showcase his journey and how he handles these tasks with `smolagents`!
在本单元中，第一单元的智能体阿尔弗雷德（Alfred）回归了。这次，他使用 `smolagents` 框架进行内部运作。我们将一起探索这个框架背后的关键概念，同时阿尔弗雷德将处理各种任务。阿尔弗雷德正在韦恩庄园（Wayne Manor）组织一场派对，趁韦恩家族🦇外出时，他有很多事情要做。跟随我们一起展示他的旅程，看他如何使用 `smolagents` 处理这些任务！
<Tip>
In this unit, you will learn to build AI agents with the `smolagents` library. Your agents will be able to search for data, execute code, and interact with web pages. You will also learn how to combine multiple agents to create more powerful systems.
在本单元中，您将学习使用 `smolagents` 库构建AI智能体。您的智能体将能够搜索数据、执行代码并与网页交互。您还将学习如何结合多个智能体来创建更强大的系统。
</Tip>
![Alfred the agent](https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/this-is-alfred.jpg)
## Contents
## 内容
During this unit on `smolagents`, we cover:
在这个关于 `smolagents` 的单元中，我们涵盖：
### 1️⃣ [Why Use smolagents](./why_use_smolagents)
### 1️⃣ [为什么使用 smolagents](./why_use_smolagents)
`smolagents` is one of the many open-source agent frameworks available for application development. Alternative options include `LlamaIndex` and `LangGraph`, which are also covered in other modules in this course. `smolagents` offers several key features that might make it a great fit for specific use cases, but we should always consider all options when selecting a framework. We'll explore the advantages and drawbacks of using `smolagents`, helping you make an informed decision based on your project's requirements.
`smolagents` 是众多可用于应用程序开发的开源智能体框架之一。其他选择包括 `LlamaIndex` 和 `LangGraph`，这些在本课程的其他模块中也有涵盖。`smolagents` 提供了几个关键特性，可能使其非常适合特定用例，但在选择框架时，我们应该始终考虑所有选项。我们将探讨使用 `smolagents` 的优势和缺点，帮助您根据项目需求做出明智的决定。
### 2️⃣ [CodeAgents](./code_agents)
### 2️⃣ [代码智能体](./code_agents)
`CodeAgents` are the primary type of agent in `smolagents`. Instead of generating JSON or text, these agents produce Python code to perform actions. This module explores their purpose, functionality, and how they work, along with hands-on examples to showcase their capabilities.
`CodeAgents`（代码智能体）是 `smolagents` 中的主要智能体类型。这些智能体不是生成 JSON 或文本，而是生成 Python 代码来执行操作。本模块探讨它们的目的、功能以及工作原理，并提供实际例子来展示它们的能力。
### 3️⃣ [ToolCallingAgents](./tool_calling_agents)
### 3️⃣ [工具调用智能体](./tool_calling_agents)
`ToolCallingAgents` are the second type of agent supported by `smolagents`. Unlike `CodeAgents`, which generate Python code, these agents rely on JSON/text blobs that the system must parse and interpret to execute actions. This module covers their functionality, their key differences from `CodeAgents`, and it provides an example to illustrate their usage.
`ToolCallingAgents`（工具调用智能体）是 `smolagents` 支持的第二种智能体类型。与生成 Python 代码的 `CodeAgents` 不同，这些智能体依赖于系统必须解析和解释以执行操作的 JSON/文本块。本模块涵盖它们的功能、与 `CodeAgents` 的主要区别，并提供示例说明其用法。
### 4️⃣ [Tools](./tools)
### 4️⃣ [工具](./tools)
As we saw in Unit 1, tools are functions that an LLM can use within an agentic system, and they act as the essential building blocks for agent behavior. This module covers how to create tools, their structure, and different implementation methods using the `Tool` class or the `@tool` decorator. You'll also learn about the default toolbox, how to share tools with the community, and how to load community-contributed tools for use in your agents.
正如我们在第 1 单元中看到的，工具是大语言模型（LLM）可以在智能体系统中使用的函数，它们作为智能体行为的基本构建块。本模块涵盖如何创建工具、它们的结构，以及使用 `Tool` 类或 `@tool` 装饰器的不同实现方法。您还将了解默认工具箱、如何与社区共享工具，以及如何加载社区贡献的工具以在您的智能体中使用。
### 5️⃣ [Retrieval Agents](./retrieval_agents)
### 5️⃣ [检索智能体](./retrieval_agents)
Retrieval agents allow models access to knowledge bases, making it possible to search, synthesize, and retrieve information from multiple sources. They leverage vector stores for efficient retrieval and implement **Retrieval-Augmented Generation (RAG)** patterns. These agents are particularly useful for integrating web search with custom knowledge bases while maintaining conversation context through memory systems. This module explores implementation strategies, including fallback mechanisms for robust information retrieval.
检索智能体（Retrieval agents）使模型能够访问知识库，从而可以从多个来源搜索、综合和检索信息。它们利用向量存储（vector stores）进行高效检索，并实现**检索增强生成（Retrieval-Augmented Generation，RAG）**模式。这些智能体特别适用于将网络搜索与自定义知识库集成，同时通过记忆系统维持对话上下文。本模块探讨实施策略，包括用于稳健信息检索的回退机制。
### 6️⃣ [Multi-Agent Systems](./multi_agent_systems)
### 6️⃣ [多智能体系统](./multi_agent_systems)
Orchestrating multiple agents effectively is crucial for building powerful, multi-agent systems. By combining agents with different capabilities—such as a web search agent with a code execution agent—you can create more sophisticated solutions. This module focuses on designing, implementing, and managing multi-agent systems to maximize efficiency and reliability.
有效地编排多个智能体对于构建强大的多智能体系统至关重要。通过组合具有不同能力的智能体（例如，将网络搜索智能体与代码执行智能体结合），您可以创建更复杂的解决方案。本模块专注于设计、实施和管理多智能体系统，以最大限度地提高效率和可靠性。
### 7️⃣ [Vision and Browser agents](./vision_agents)
### 7️⃣ [视觉和浏览器智能体](./vision_agents)
Vision agents extend traditional agent capabilities by incorporating **Vision-Language Models (VLMs)**, enabling them to process and interpret visual information. This module explores how to design and integrate VLM-powered agents, unlocking advanced functionalities like image-based reasoning, visual data analysis, and multimodal interactions. We will also use vision agents to build a browser agent that can browse the web and extract information from it.
视觉智能体（Vision agents）通过整合**视觉-语言模型（Vision-Language Models，VLMs）**扩展了传统智能体的能力，使其能够处理和解释视觉信息。本模块探讨如何设计和集成由 VLM 驱动的智能体，从而解锁诸如基于图像的推理、视觉数据分析和多模态交互等高级功能。我们还将使用视觉智能体构建一个浏览器智能体，能够浏览网络并从中提取信息。
## Resources
## 资源
- [smolagents Documentation](https://huggingface.co/docs/smolagents) - Official docs for the smolagents library
- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) - Research paper on agent architectures
- [Agent Guidelines](https://huggingface.co/docs/smolagents/tutorials/building_good_agents) - Best practices for building reliable agents
- [LangGraph Agents](https://langchain-ai.github.io/langgraph/) - Additional examples of agent implementations
- [Function Calling Guide](https://platform.openai.com/docs/guides/function-calling) - Understanding function calling in LLMs
- [RAG Best Practices](https://www.pinecone.io/learn/retrieval-augmented-generation/) - Guide to implementing effective RAG
- [smolagents 文档](https://huggingface.co/docs/smolagents) - smolagents 库的官方文档
- [构建有效的智能体](https://www.anthropic.com/research/building-effective-agents) - 关于智能体架构的研究论文
- [智能体指南](https://huggingface.co/docs/smolagents/tutorials/building_good_agents) - 构建可靠智能体的最佳实践
- [LangGraph 智能体](https://langchain-ai.github.io/langgraph/) - 智能体实现的其他示例
- [函数调用指南](https://platform.openai.com/docs/guides/function-calling) - 了解大语言模型中的函数调用
- [RAG 最佳实践](https://www.pinecone.io/learn/retrieval-augmented-generation/) - 实施有效 RAG 的指南

126
units/zh-CN/unit2/smolagents/multi_agent_systems.mdx
View File

@@ -4,59 +4,59 @@
{label: "Google Colab", value: "https://colab.research.google.com/github/huggingface/agents-course/blob/main/notebooks/unit2/smolagents/multiagent_notebook.ipynb"},
]} />
# Multi-Agent Systems
# 多智能体系统
Multi-agent systems enable **specialized agents to collaborate on complex tasks**, improving modularity, scalability, and robustness. Instead of relying on a single agent, tasks are distributed among agents with distinct capabilities.
多智能体系统使**专业智能体能够在复杂任务上进行协作**，提高模块化、可扩展性和稳健性。不依赖单一智能体，任务分配给具有不同能力的智能体。
In **smolagents**, different agents can be combined to generate Python code, call external tools, perform web searches, and more. By orchestrating these agents, we can create powerful workflows.
在 **smolagents** 中，不同的智能体可以组合起来生成 Python 代码、调用外部工具、执行网络搜索等。通过编排这些智能体，我们可以创建强大的工作流。
A typical setup might include:
- A **Manager Agent** for task delegation
- A **Code Interpreter Agent** for code execution
- A **Web Search Agent** for information retrieval
一个典型的设置可能包括：
- **管理智能体（Manager Agent）**用于任务委派
- **代码解释器智能体（Code Interpreter Agent）**用于代码执行
- **网络搜索智能体（Web Search Agent）**用于信息检索
The diagram below illustrates a simple multi-agent architecture where a **Manager Agent** coordinates a **Code Interpreter Tool** and a **Web Search Agent**, which in turn utilizes tools like the `DuckDuckGoSearchTool` and `VisitWebpageTool` to gather relevant information.
下图说明了一个简单的多智能体架构，其中**管理智能体**协调**代码解释器工具**和**网络搜索智能体**，后者利用像 `DuckDuckGoSearchTool` 和 `VisitWebpageTool` 这样的工具来收集相关信息。
<img src="https://mermaid.ink/img/pako:eNp1kc1qhTAQRl9FUiQb8wIpdNO76eKubrmFks1oRg3VSYgjpYjv3lFL_2hnMWQOJwn5sqgmelRWleUSKLAtFs09jqhtoWuYUFfFAa6QA9QDTnpzamheuhxn8pt40-6l13UtS0ddhtQXj6dbR4XUGQg6zEYasTF393KjeSDGnDJKNxzj8I_7hLW5IOSmP9CH9hv_NL-d94d4DVNg84p1EnK4qlIj5hGClySWbadT-6OdsrL02MI8sFOOVkciw8zx8kaNspxnrJQE0fXKtjBMMs3JA-MpgOQwftIE9Bzj14w-cMznI_39E9Z3p0uFoA?type=png" style='background: white;'>
## Multi-Agent Systems in Action
## 多智能体系统实战
A multi-agent system consists of multiple specialized agents working together under the coordination of an **Orchestrator Agent**. This approach enables complex workflows by distributing tasks among agents with distinct roles.
多智能体系统由多个专业智能体在**编排智能体（Orchestrator Agent）**的协调下共同工作组成。这种方法通过在具有不同角色的智能体之间分配任务来实现复杂的工作流。
For example, a **Multi-Agent RAG system** can integrate:
- A **Web Agent** for browsing the internet.
- A **Retriever Agent** for fetching information from knowledge bases.
- An **Image Generation Agent** for producing visuals.
例如，**多智能体 RAG 系统**可以整合：
- **网络智能体（Web Agent）**用于浏览互联网。
- **检索智能体（Retriever Agent）**用于从知识库获取信息。
- **图像生成智能体（Image Generation Agent）**用于生成视觉内容。
All of these agents operate under an orchestrator that manages task delegation and interaction.
所有这些智能体在管理任务委派和交互的编排者下运行。
## Solving a complex task with a multi-agent hierarchy
## 用多智能体层次结构解决复杂任务
<Tip>
You can follow the code in <a href="https://huggingface.co/agents-course/notebooks/blob/main/unit2/smolagents/multiagent_notebook.ipynb" target="_blank">this notebook</a> that you can run using Google Colab.
你可以在 <a href="https://huggingface.co/agents-course/notebooks/blob/main/unit2/smolagents/multiagent_notebook.ipynb" target="_blank">这个笔记本</a> 中跟随代码，可以使用 Google Colab 运行。
</Tip>
The reception is approaching! With your help, Alfred is now nearly finished with the preparations.
接待会即将到来！在你的帮助下，阿尔弗雷德现在几乎完成了准备工作。
But now there's a problem: the Batmobile has disappeared. Alfred needs to find a replacement, and find it quickly.
但现在有个问题：蝙蝠车不见了。阿尔弗雷德需要找到替代品，而且要快。
Fortunately, a few biopics have been done on Bruce Wayne's life, so maybe Alfred could get a car left behind on one of the movie sets, and re-engineer it up to modern standards, which certainly would include a full self-driving option.
幸运的是，已经有一些关于布鲁斯·韦恩生活的传记电影，所以也许阿尔弗雷德可以从某个电影拍摄现场留下的汽车中获取一辆，并将其重新改造到现代标准，这当然会包括完全自动驾驶选项。
But this could be anywhere in the filming locations around the world - which could be numerous.
但这可能在世界各地的任何拍摄地点——可能数量众多。
So Alfred wants your help. Could you build an agent able to solve this task?
所以阿尔弗雷德需要你的帮助。你能构建一个能够解决这个任务的智能体吗？
> 👉 Find all Batman filming locations in the world, calculate the time to transfer via boat to there, and represent them on a map, with a color varying by boat transfer time. Also represent some supercar factories with the same boat transfer time.
Let's build this!
让我们来构建这个！
This example needs some additional packages, so let's install them first:
这个例子需要一些额外的包，所以首先安装它们：
```bash
pip install 'smolagents[litellm]' matplotlib geopandas shapely kaleido -q
```
### We first make a tool to get the cargo plane transfer time.
### 我们首先制作一个工具来获取货运飞机转运时间。
```python
import math
@@ -69,7 +69,7 @@ from smolagents import tool
def calculate_cargo_travel_time(
origin_coords: Tuple[float, float],
destination_coords: Tuple[float, float],
cruising_speed_kmh: Optional[float] = 750.0, # Average speed for cargo planes
cruising_speed_kmh: Optional[float] = 750.0, # 货运飞机的平均速度
) -> float:
"""
Calculate the travel time for a cargo plane between two points on Earth using great-circle distance.
@@ -90,14 +90,14 @@ def calculate_cargo_travel_time(
def to_radians(degrees: float) -> float:
return degrees * (math.pi / 180)
# Extract coordinates
# 提取坐标
lat1, lon1 = map(to_radians, origin_coords)
lat2, lon2 = map(to_radians, destination_coords)
# Earth's radius in kilometers
# 地球半径（公里）
EARTH_RADIUS_KM = 6371.0
# Calculate great-circle distance using the haversine formula
# 使用半正矢公式计算大圆距离
dlon = lon2 - lon1
dlat = lat2 - lat1
@@ -108,27 +108,27 @@ def calculate_cargo_travel_time(
c = 2 * math.asin(math.sqrt(a))
distance = EARTH_RADIUS_KM * c
# Add 10% to account for non-direct routes and air traffic controls
# 增加10%以考虑非直接路线和空中交通管制
actual_distance = distance * 1.1
# Calculate flight time
# Add 1 hour for takeoff and landing procedures
# 计算飞行时间
# 为起飞和着陆程序增加1小时
flight_time = (actual_distance / cruising_speed_kmh) + 1.0
# Format the results
# 格式化结果
return round(flight_time, 2)
print(calculate_cargo_travel_time((41.8781, -87.6298), (-33.8688, 151.2093)))
```
### Setting up the agent
### 设置智能体
For the model provider, we use Together AI, one of the new [inference providers on the Hub](https://huggingface.co/blog/inference-providers)!
对于模型提供商，我们使用 Together AI，这是 [Hub 上的新推理提供商](https://huggingface.co/blog/inference-providers)之一！
The GoogleSearchTool uses the [Serper API](https://serper.dev) to search the web, so this requires either having setup env variable `SERPAPI_API_KEY` and passing `provider="serpapi"` or having `SERPER_API_KEY` and passing `provider=serper`.
GoogleSearchTool 使用 [Serper API](https://serper.dev) 搜索网络，因此这需要设置环境变量 `SERPAPI_API_KEY` 并传递 `provider="serpapi"` 或者拥有 `SERPER_API_KEY` 并传递 `provider=serper`。
If you don't have any Serp API provider setup, you can use `DuckDuckGoSearchTool` but beware that it has a rate limit.
如果你没有设置任何 Serp API 提供商，你可以使用 `DuckDuckGoSearchTool`，但请注意它有速率限制。
```python
import os
@@ -138,7 +138,7 @@ from smolagents import CodeAgent, GoogleSearchTool, HfApiModel, VisitWebpageTool
model = HfApiModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct", provider="together")
```
We can start by creating a simple agent as a baseline to give us a simple report.
我们可以先创建一个简单的智能体作为基线，为我们提供一个简单的报告。
```python
task = """Find all Batman filming locations in the world, calculate the time to transfer via cargo plane to here (we're in Gotham, 40.7128° N, 74.0060° W), and return them to me as a pandas dataframe.
@@ -162,7 +162,7 @@ result = agent.run(task)
result
```
In our case, it generates this output:
在我们的例子中，它生成了这个输出：
```python
| | Location | Travel Time to Gotham (hours) |
@@ -185,9 +185,9 @@ In our case, it generates this output:
| 15 | Woking, UK (McLaren) | 9.13 |
```
We could already improve this a bit by throwing in some dedicated planning steps, and adding more prompting.
我们可以通过添加一些专门的规划步骤和更多的提示来进一步改进这一点。
Planning steps allow the agent to think ahead and plan its next steps, which can be useful for more complex tasks.
规划步骤允许智能体提前思考并规划其下一步行动，这对于更复杂的任务非常有用。
```python
agent.planning_interval = 4
@@ -207,7 +207,7 @@ print(detailed_report)
detailed_report
```
In our case, it generates this output:
在我们的例子中，它生成了这个输出：
```python
| | Location | Travel Time (hours) |
@@ -217,21 +217,21 @@ In our case, it generates this output:
```
Thanks to these quick changes, we obtained a much more concise report by simply providing our agent a detailed prompt, and giving it planning capabilities!
感谢这些快速更改，我们通过简单地为我们的智能体提供详细提示，并赋予它规划能力，获得了更加简洁的报告！
The model's context window is quickly filling up. So **if we ask our agent to combine the results of detailed search with another, it will be slower and quickly ramp up tokens and costs**.
模型的上下文窗口正在快速填满。所以**如果我们要求我们的智能体将详细搜索的结果与另一个结合起来，它将变得更慢，并且会迅速增加令牌数量和成本**。
➡️ We need to improve the structure of our system.
➡️ 我们需要改进系统的结构。
### ✌️ Splitting the task between two agents
### ✌️ 在两个智能体之间分割任务
Multi-agent structures allow to separate memories between different sub-tasks, with two great benefits:
- Each agent is more focused on its core task, thus more performant
- Separating memories reduces the count of input tokens at each step, thus reducing latency and cost.
多智能体结构允许在不同子任务之间分离记忆，带来两大好处：
- 每个智能体更专注于其核心任务，因此性能更佳
- 分离记忆减少了每个步骤的输入令牌数量，从而减少延迟和成本。
Let's create a team with a dedicated web search agent, managed by another agent.
让我们创建一个团队，包含一个专门的网络搜索智能体，由另一个智能体管理。
The manager agent should have plotting capabilities to write its final report: so let us give it access to additional imports, including `matplotlib`, and `geopandas` + `shapely` for spatial plotting.
管理智能体应该具有绘图功能来编写其最终报告：因此让我们给它访问额外导入的权限，包括 `matplotlib` 和 `geopandas` + `shapely` 用于空间绘图。
```python
model = HfApiModel(
@@ -252,9 +252,9 @@ web_agent = CodeAgent(
)
```
The manager agent will need to do some mental heavy lifting.
管理智能体需要进行一些较重的思考工作。
So we give it the stronger model [DeepSeek-R1](https://huggingface.co/deepseek-ai/DeepSeek-R1), and add a `planning_interval` to the mix.
所以我们给它更强大的模型 [DeepSeek-R1](https://huggingface.co/deepseek-ai/DeepSeek-R1)，并添加 `planning_interval` 到组合中。
```python
from smolagents.utils import encode_image_base64, make_image_url
@@ -315,13 +315,13 @@ manager_agent = CodeAgent(
)
```
Let us inspect what this team looks like:
让我们检查这个团队是什么样子：
```python
manager_agent.visualize()
```
This will generate something like this, helping us understand the structure and relationship between agents and tools used:
这将生成类似于下面的内容，帮助我们理解智能体和使用的工具之间的结构和关系：
```python
CodeAgent | deepseek-ai/DeepSeek-R1
@@ -394,20 +394,20 @@ Never try to process strings using code: when you have a string to read, just pr
""")
```
I don't know how that went in your run, but in mine, the manager agent skilfully divided tasks given to the web agent in `1. Search for Batman filming locations`, then `2. Find supercar factories`, before aggregating the lists and plotting the map.
我不知道在你的运行中情况如何，但在我的运行中，管理智能体巧妙地将任务分配给网络智能体，首先是 `1. Search for Batman filming locations`，然后是 `2. Find supercar factories`，最后聚合列表并绘制地图。
Let's see what the map looks like by inspecting it directly from the agent state:
让我们通过直接从智能体状态查看地图：
```python
manager_agent.python_executor.state["fig"]
```
This will output the map:
这将输出地图：
![Multiagent system example output map](https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit2/smolagents/output_map.png)
![多智能体系统示例输出地图](https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit2/smolagents/output_map.png)
## Resources
## 资源
- [Multi-Agent Systems](https://huggingface.co/docs/smolagents/main/en/examples/multiagents) – Overview of multi-agent systems.
- [What is Agentic RAG?](https://weaviate.io/blog/what-is-agentic-rag) – Introduction to Agentic RAG.
- [Multi-Agent RAG System 🤖🤝🤖 Recipe](https://huggingface.co/learn/cookbook/multiagent_rag_system) – Step-by-step guide to building a multi-agent RAG system.
- [多智能体系统](https://huggingface.co/docs/smolagents/main/en/examples/multiagents) – 多智能体系统概述。
- [什么是智能体 RAG？](https://weaviate.io/blog/what-is-agentic-rag) – 智能体 RAG 介绍。
- [多智能体 RAG 系统 🤖🤝🤖 配方](https://huggingface.co/learn/cookbook/multiagent_rag_system) – 构建多智能体 RAG 系统的分步指南。

108
units/zh-CN/unit2/smolagents/quiz1.mdx
View File

@@ -1,142 +1,142 @@
# Small Quiz (ungraded) [[quiz1]]
# 小测验 (不计分) [[quiz1]]
Let's test your understanding of `smolagents` with a quick quiz! Remember, testing yourself helps reinforce learning and identify areas that may need review.
让我们用一个快速测验来测试你对 `smolagents` 的理解！请记住，自我测试有助于强化学习并识别可能需要复习的领域。
This is an optional quiz and it's not graded.
这是一个可选测验，不计分。
### Q1: What is one of the primary advantages of choosing `smolagents` over other frameworks?
Which statement best captures a core strength of the `smolagents` approach?
### Q1: 选择 `smolagents` 而非其他框架的主要优势之一是什么？
哪个陈述最能体现 `smolagents` 方法的核心优势？
<Question
choices={[
{
text: "It uses highly specialized configuration files and a steep learning curve to ensure only expert developers can use it",
explain: "smolagents is designed for simplicity and minimal code complexity, not steep learning curves.",
text: "它使用高度专业化的配置文件和陡峭的学习曲线，确保只有专业开发人员能够使用它",
explain: "smolagents 设计注重简单性和最小代码复杂性，而不是陡峭的学习曲线。",
},
{
text: "It supports a code-first approach with minimal abstractions, letting agents interact directly via Python function calls",
explain: "Yes, smolagents emphasizes a straightforward, code-centric design with minimal abstractions.",
text: "它支持代码优先方法，具有最少的抽象，让智能体通过 Python 函数调用直接交互",
explain: "是的，smolagents 强调直接、以代码为中心的设计，具有最小的抽象。",
correct: true
},
{
text: "It focuses on JSON-based actions, removing the need for agents to write any code",
explain: "While smolagents supports JSON-based tool calls (ToolCallingAgents), the library emphasizes code-based approaches with CodeAgents.",
text: "它专注于基于 JSON 的操作，消除了智能体编写任何代码的需求",
explain: "虽然 smolagents 支持基于 JSON 的工具调用（ToolCallingAgents），但该库强调基于代码的方法，如 CodeAgents。",
},
{
text: "It deeply integrates with a single LLM provider and specialized hardware",
explain: "smolagents supports multiple model providers and does not require specialized hardware.",
text: "它与单一 LLM 提供商和专用硬件深度集成",
explain: "smolagents 支持多种模型提供商，并且不需要专用硬件。",
}
]}
/>
---
### Q2: In which scenario would you likely benefit most from using smolagents?
Which situation aligns well with what smolagents does best?
### Q2: 在哪种情况下，你可能最能从使用 smolagents 中受益？
哪种情况最符合 smolagents 的优势？
<Question
choices={[
{
text: "Building a large-scale enterprise system where you need dozens of microservices and real-time data pipelines",
explain: "While possible, smolagents is more focused on lightweight, code-centric experimentation rather than heavy enterprise infrastructure.",
text: "构建大型企业系统，需要数十个微服务和实时数据管道",
explain: "虽然可能，但 smolagents 更专注于轻量级、以代码为中心的实验，而不是重型企业基础设施。",
},
{
text: "Prototyping or experimenting quickly with agent logic, particularly when your application is relatively straightforward",
explain: "Yes. smolagents is designed for simple and nimble agent creation without extensive setup overhead.",
text: "快速原型设计或实验智能体逻辑，特别是当你的应用相对简单直接时",
explain: "是的。smolagents 设计用于简单灵活的智能体创建，无需大量设置开销。",
correct: true
},
{
text: "Needing a framework that only supports cloud-based LLMs and forbids local inference",
explain: "smolagents offers flexible integration with local or hosted models, not exclusively cloud-based LLMs.",
text: "需要一个只支持基于云的 LLM 并禁止本地推理的框架",
explain: "smolagents 提供与本地或托管模型的灵活集成，不仅限于基于云的 LLM。",
},
{
text: "A scenario that requires advanced orchestration, multi-modal perception, and enterprise-scale features out-of-the-box",
explain: "While you can integrate advanced capabilities, smolagents itself is lightweight and minimal at its core.",
text: "需要高级编排、多模态感知和开箱即用的企业级功能的场景",
explain: "虽然你可以集成高级功能，但 smolagents 本身在核心上是轻量级和简约的。",
}
]}
/>
---
### Q3: smolagents offers flexibility in model integration. Which statement best reflects its approach?
Choose the most accurate description of how smolagents interoperates with LLMs.
### Q3: smolagents 在模型集成方面提供了灵活性。哪个陈述最能反映其方法？
选择最准确描述 smolagents 如何与 LLM 互操作的说明。
<Question
choices={[
{
text: "It only provides a single built-in model and does not allow custom integrations",
explain: "smolagents supports multiple different backends and user-defined models.",
text: "它只提供一个内置模型，不允许自定义集成",
explain: "smolagents 支持多种不同的后端和用户定义的模型。",
},
{
text: "It can be used with a wide range of LLMs, offering predefined classes like TransformersModel, HfApiModel, and LiteLLMModel",
explain: "This is correct. smolagents supports flexible model integration through various classes.",
text: "它可以与广泛的 LLM 一起使用，提供预定义的类如 TransformersModel、HfApiModel 和 LiteLLMModel",
explain: "这是正确的。smolagents 通过各种类支持灵活的模型集成。",
correct: true
},
{
text: "It requires you to implement your own model connector for every LLM usage",
explain: "There are multiple prebuilt connectors that make LLM integration straightforward.",
text: "它要求你为每次 LLM 使用实现自己的模型连接器",
explain: "有多种预构建的连接器使 LLM 集成变得简单直接。",
},
{
text: "It only integrates with open-source LLMs but not commercial APIs",
explain: "smolagents can integrate with both open-source and commercial model APIs.",
text: "它只与开源 LLM 集成，不支持商业 API",
explain: "smolagents 可以与开源和商业模型 API 集成。",
}
]}
/>
---
### Q4: How does smolagents handle the debate between code-based actions and JSON-based actions?
Which statement correctly characterizes smolagents' philosophy about action formats?
### Q4: smolagents 如何处理基于代码的操作和基于 JSON 的操作之间的争论？
哪个陈述正确地描述了 smolagents 关于操作格式的理念？
<Question
choices={[
{
text: "It only allows JSON-based actions for all agent tasks, requiring a parser to extract the tool calls",
explain: "ToolCallingAgent uses JSON-based calls, but smolagents also provides a primary CodeAgent option that writes Python code.",
text: "它只允许所有智能体任务使用基于 JSON 的操作，需要解析器来提取工具调用",
explain: "ToolCallingAgent 使用基于 JSON 的调用，但 smolagents 也提供主要的 CodeAgent 选项，可以编写 Python 代码。",
},
{
text: "It focuses on code-based actions via a CodeAgent but also supports JSON-based tool calls with a ToolCallingAgent",
explain: "Yes, smolagents primarily recommends code-based actions but includes a JSON-based alternative for users who prefer it or need it.",
text: "它通过 CodeAgent 专注于基于代码的操作，但也通过 ToolCallingAgent 支持基于 JSON 的工具调用",
explain: "是的，smolagents 主要推荐基于代码的操作，但也为喜欢或需要它的用户提供了基于 JSON 的替代方案。",
correct: true
},
{
text: "It disallows any external function calls, instead requiring all logic to reside entirely within the LLM",
explain: "smolagents is specifically designed to grant LLMs the ability to call tools or code externally.",
text: "它禁止任何外部函数调用，而是要求所有逻辑完全存在于 LLM 内部",
explain: "smolagents 专门设计用于授予 LLM 调用外部工具或代码的能力。",
},
{
text: "It requires users to manually convert every code snippet into a JSON object before running the agent",
explain: "smolagents can automatically manage code snippet creation within the CodeAgent path, no manual JSON conversion necessary.",
text: "它要求用户在运行智能体之前手动将每个代码片段转换为 JSON 对象",
explain: "smolagents 可以在 CodeAgent 路径中自动管理代码片段创建，无需手动 JSON 转换。",
}
]}
/>
---
### Q5: How does smolagents integrate with the Hugging Face Hub for added benefits?
Which statement accurately describes one of the core advantages of Hub integration?
### Q5: smolagents 如何与 Hugging Face Hub 集成以获得额外优势？
哪个陈述准确描述了 Hub 集成的核心优势之一？
<Question
choices={[
{
text: "It automatically upgrades all public models to commercial license tiers",
explain: "Hub integration doesn't change the license tier for models or tools.",
text: "它自动将所有公共模型升级到商业许可层级",
explain: "Hub 集成不会改变模型或工具的许可层级。",
},
{
text: "It allows you to push and share agents or tools, making them easily discoverable and reusable by other developers",
explain: "Correct. smolagents supports uploading agents and tools to the HF Hub for others to reuse.",
text: "它允许你推送和共享智能体或工具，使其他开发者易于发现和重用",
explain: "正确。smolagents 支持将智能体和工具上传到 HF Hub 供他人重用。",
correct: true
},
{
text: "It disables local inference entirely, forcing remote model usage only",
explain: "Users can still do local inference if they prefer; pushing to the Hub doesn't override local usage.",
text: "它完全禁用本地推理，只强制使用远程模型",
explain: "如果用户愿意，仍然可以进行本地推理；推送到 Hub 不会覆盖本地使用。",
},
{
text: "It permanently stores all your code-based agents, preventing any updates or versioning",
explain: "Hub repositories support updates and version control, so you can revise your code-based agents any time.",
text: "它永久存储所有基于代码的智能体，防止任何更新或版本控制",
explain: "Hub 仓库支持更新和版本控制，因此你可以随时修改基于代码的智能体。",
}
]}
/>
---
Congratulations on completing this quiz! 🎉 If you missed any questions, consider reviewing the *Why use smolagents* section for a deeper understanding. If you did well, you're ready to explore more advanced topics in smolagents!
恭喜你完成了这个测验！🎉 如果你错过了任何问题，可以考虑复习*为什么使用 smolagents*部分以更深入理解。如果你表现良好，你已经准备好探索 smolagents 中更高级的主题了！