diff --git a/docs/source/zh/reference/agents.md b/docs/source/zh/reference/agents.md index e5e51188c..bd7f3a779 100644 --- a/docs/source/zh/reference/agents.md +++ b/docs/source/zh/reference/agents.md @@ -1,3 +1,4 @@ + -# Agents +# Agents（智能体） -Smolagents is an experimental API which is subject to change at any time. Results returned by the agents -can vary as the APIs or underlying models are prone to change. +Smolagents 是一个实验性的 API，可能会随时发生变化。由于 API 或底层模型可能发生变化，代理返回的结果也可能有所不同。 -To learn more about agents and tools make sure to read the [introductory guide](../index). This page -contains the API docs for the underlying classes. - -## Agents +要了解有关智能体和工具的更多信息，请务必阅读[入门指南](../index)。本页面包含基础类的 API 文档。 -Our agents inherit from [`MultiStepAgent`], which means they can act in multiple steps, each step consisting of one thought, then one tool call and execution. Read more in [this conceptual guide](../conceptual_guides/react). +## 智能体（Agents） -We provide two types of agents, based on the main [`Agent`] class. - - [`CodeAgent`] is the default agent, it writes its tool calls in Python code. - - [`ToolCallingAgent`] writes its tool calls in JSON. +我们的智能体继承自 [`MultiStepAgent`]，这意味着它们可以执行多步操作，每一步包含一个思考（thought），然后是一个工具调用和执行。请阅读[概念指南](../conceptual_guides/react)以了解更多信息。 -Both require arguments `model` and list of tools `tools` at initialization. +我们提供两种类型的代理，它们基于主要的 [`Agent`] 类： + - [`CodeAgent`] 是默认代理，它以 Python 代码编写工具调用。 + - [`ToolCallingAgent`] 以 JSON 编写工具调用。 +两者在初始化时都需要提供参数 `model` 和工具列表 `tools`。 -### Classes of agents +### 智能体类 [[autodoc]] MultiStepAgent @@ -44,10 +42,9 @@ Both require arguments `model` and list of tools `tools` at initialization. [[autodoc]] ToolCallingAgent - ### ManagedAgent -_This class is deprecated since 1.8.0: now you just need to pass name and description attributes to an agent to directly use it as previously done with a ManagedAgent._ +_此类自 1.8.0 起已被弃用：现在您只需向普通代理传递 `name` 和 `description` 属性即可使其可被管理代理调用。_ ### stream_to_gradio @@ -56,99 +53,11 @@ _This class is deprecated since 1.8.0: now you just need to pass name and descri ### GradioUI > [!TIP] -> You must have `gradio` installed to use the UI. Please run `pip install smolagents[gradio]` if it's not the case. +> 您必须安装 `gradio` 才能使用 UI。如果尚未安装，请运行 `pip install smolagents[gradio]`。 [[autodoc]] GradioUI -## Models - -You're free to create and use your own models to power your agent. - -You could use any `model` callable for your agent, as long as: -1. It follows the [messages format](./chat_templating) (`List[Dict[str, str]]`) for its input `messages`, and it returns a `str`. -2. It stops generating outputs *before* the sequences passed in the argument `stop_sequences` - -For defining your LLM, you can make a `custom_model` method which accepts a list of [messages](./chat_templating) and returns text. This callable also needs to accept a `stop_sequences` argument that indicates when to stop generating. - -```python -from huggingface_hub import login, InferenceClient - -login("") - -model_id = "meta-llama/Llama-3.3-70B-Instruct" - -client = InferenceClient(model=model_id) - -def custom_model(messages, stop_sequences=["Task"]) -> str: - response = client.chat_completion(messages, stop=stop_sequences, max_tokens=1000) - answer = response.choices[0].message.content - return answer -``` - -Additionally, `custom_model` can also take a `grammar` argument. In the case where you specify a `grammar` upon agent initialization, this argument will be passed to the calls to model, with the `grammar` that you defined upon initialization, to allow [constrained generation](https://huggingface.co/docs/text-generation-inference/conceptual/guidance) in order to force properly-formatted agent outputs. - -### TransformersModel - -For convenience, we have added a `TransformersModel` that implements the points above by building a local `transformers` pipeline for the model_id given at initialization. - -```python -from smolagents import TransformersModel - -model = TransformersModel(model_id="HuggingFaceTB/SmolLM-135M-Instruct") - -print(model([{"role": "user", "content": "Ok!"}], stop_sequences=["great"])) -``` -```text ->>> What a -``` - -> [!TIP] -> You must have `transformers` and `torch` installed on your machine. Please run `pip install smolagents[transformers]` if it's not the case. - -[[autodoc]] TransformersModel - -### HfApiModel - -The `HfApiModel` wraps an [HF Inference API](https://huggingface.co/docs/api-inference/index) client for the execution of the LLM. - -```python -from smolagents import HfApiModel - -messages = [ - {"role": "user", "content": "Hello, how are you?"}, - {"role": "assistant", "content": "I'm doing great. How can I help you today?"}, - {"role": "user", "content": "No need to help, take it easy."}, -] - -model = HfApiModel() -print(model(messages)) -``` -```text ->>> Of course! If you change your mind, feel free to reach out. Take care! -``` -[[autodoc]] HfApiModel - -### LiteLLMModel - -The `LiteLLMModel` leverages [LiteLLM](https://www.litellm.ai/) to support 100+ LLMs from various providers. -You can pass kwargs upon model initialization that will then be used whenever using the model, for instance below we pass `temperature`. - -```python -from smolagents import LiteLLMModel - -messages = [ - {"role": "user", "content": "Hello, how are you?"}, - {"role": "assistant", "content": "I'm doing great. How can I help you today?"}, - {"role": "user", "content": "No need to help, take it easy."}, -] - -model = LiteLLMModel("anthropic/claude-3-5-sonnet-latest", temperature=0.2, max_tokens=10) -print(model(messages)) -``` - -[[autodoc]] LiteLLMModel - -## Prompts +## 提示（Prompts） [[autodoc]] smolagents.agents.PromptTemplates diff --git a/docs/source/zh/reference/models.md b/docs/source/zh/reference/models.md new file mode 100644 index 000000000..79c9e72a4 --- /dev/null +++ b/docs/source/zh/reference/models.md @@ -0,0 +1,166 @@ + + +# 模型 + + + +Smolagents 是一个实验性 API，其可能会随时发生更改。由于 API 或底层模型可能会变化，智能体返回的结果可能会有所不同。 + + + +要了解有关智能体和工具的更多信息，请务必阅读[入门指南](../index)。此页面包含底层类的 API 文档。 + +## 模型 + +您可以自由创建和使用自己的模型为智能体提供支持。 + +您可以使用任何 `model` 可调用对象作为智能体的模型，只要满足以下条件： +1. 它遵循[消息格式](./chat_templating)（`List[Dict[str, str]]`），将其作为输入 `messages`，并返回一个 `str`。 +2. 它在生成的序列到达 `stop_sequences` 参数中指定的内容之前停止生成输出。 + +要定义您的 LLM，可以创建一个 `custom_model` 方法，该方法接受一个 [messages](./chat_templating) 列表，并返回一个包含 `.content` 属性的对象，其中包含生成的文本。此可调用对象还需要接受一个 `stop_sequences` 参数，用于指示何时停止生成。 + +```python +from huggingface_hub import login, InferenceClient + +login("") + +model_id = "meta-llama/Llama-3.3-70B-Instruct" + +client = InferenceClient(model=model_id) + +def custom_model(messages, stop_sequences=["Task"]): + response = client.chat_completion(messages, stop=stop_sequences, max_tokens=1000) + answer = response.choices[0].message + return answer +``` + +此外，`custom_model` 还可以接受一个 `grammar` 参数。如果在智能体初始化时指定了 `grammar`，则此参数将在调用模型时传递，以便进行[约束生成](https://huggingface.co/docs/text-generation-inference/conceptual/guidance)，从而强制生成格式正确的智能体输出。 + +### TransformersModel + +为了方便起见，我们添加了一个 `TransformersModel`，该模型通过为初始化时指定的 `model_id` 构建一个本地 `transformers` pipeline 来实现上述功能。 + +```python +from smolagents import TransformersModel + +model = TransformersModel(model_id="HuggingFaceTB/SmolLM-135M-Instruct") + +print(model([{"role": "user", "content": [{"type": "text", "text": "Ok!"}]}], stop_sequences=["great"])) +``` +```text +>>> What a +``` + +> [!TIP] +> 您必须在机器上安装 `transformers` 和 `torch`。如果尚未安装，请运行 `pip install smolagents[transformers]`。 + +[[autodoc]] TransformersModel + +### HfApiModel + +`HfApiModel` 封装了 huggingface_hub 的 [InferenceClient](https://huggingface.co/docs/huggingface_hub/main/en/guides/inference)，用于执行 LLM。它支持 HF 的 [Inference API](https://huggingface.co/docs/api-inference/index) 以及 Hub 上所有可用的[Inference Providers](https://huggingface.co/blog/inference-providers)。 + +```python +from smolagents import HfApiModel + +messages = [ + {"role": "user", "content": [{"type": "text", "text": "Hello, how are you?"}]} +] + +model = HfApiModel() +print(model(messages)) +``` +```text +>>> Of course! If you change your mind, feel free to reach out. Take care! +``` +[[autodoc]] HfApiModel + +### LiteLLMModel + +`LiteLLMModel` 利用 [LiteLLM](https://www.litellm.ai/) 支持来自不同提供商的 100+ 个 LLM。您可以在模型初始化时传递 `kwargs`，这些参数将在每次使用模型时被使用，例如下面的示例中传递了 `temperature`。 + +```python +from smolagents import LiteLLMModel + +messages = [ + {"role": "user", "content": [{"type": "text", "text": "Hello, how are you?"}]} +] + +model = LiteLLMModel("anthropic/claude-3-5-sonnet-latest", temperature=0.2, max_tokens=10) +print(model(messages)) +``` + +[[autodoc]] LiteLLMModel + +### OpenAIServerModel + +此类允许您调用任何 OpenAIServer 兼容模型。 +以下是设置方法（您可以自定义 `api_base` URL 指向其他服务器）： +```py +import os +from smolagents import OpenAIServerModel + +model = OpenAIServerModel( + model_id="gpt-4o", + api_base="https://api.openai.com/v1", + api_key=os.environ["OPENAI_API_KEY"], +) +``` + +[[autodoc]] OpenAIServerModel + +### AzureOpenAIServerModel + +`AzureOpenAIServerModel` 允许您连接到任何 Azure OpenAI 部署。 + +下面是设置示例，请注意，如果已经设置了相应的环境变量，您可以省略 `azure_endpoint`、`api_key` 和 `api_version` 参数——环境变量包括 `AZURE_OPENAI_ENDPOINT`、`AZURE_OPENAI_API_KEY` 和 `OPENAI_API_VERSION`。 + +请注意，`OPENAI_API_VERSION` 没有 `AZURE_` 前缀，这是由于底层 [openai](https://github.com/openai/openai-python) 包的设计所致。 + +```py +import os + +from smolagents import AzureOpenAIServerModel + +model = AzureOpenAIServerModel( + model_id = os.environ.get("AZURE_OPENAI_MODEL"), + azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"), + api_key=os.environ.get("AZURE_OPENAI_API_KEY"), + api_version=os.environ.get("OPENAI_API_VERSION") +) +``` + +[[autodoc]] AzureOpenAIServerModel + +### MLXModel + +```python +from smolagents import MLXModel + +model = MLXModel(model_id="HuggingFaceTB/SmolLM-135M-Instruct") + +print(model([{"role": "user", "content": "Ok!"}], stop_sequences=["great"])) +``` +```text +>>> What a +``` + +> [!TIP] +> 您必须在机器上安装 `mlx-lm`。如果尚未安装，请运行 `pip install smolagents[mlx-lm]`。 + +[[autodoc]] MLXModel diff --git a/docs/source/zh/reference/tools.md b/docs/source/zh/reference/tools.md index 847c497ea..86f19dca4 100644 --- a/docs/source/zh/reference/tools.md +++ b/docs/source/zh/reference/tools.md @@ -1,3 +1,4 @@ + -# Tools +# 工具 -Smolagents is an experimental API which is subject to change at any time. Results returned by the agents -can vary as the APIs or underlying models are prone to change. +Smolagents 是一个实验性 API，可能会随时更改。由于 API 或底层模型可能发生变化，代理返回的结果可能会有所不同。 -To learn more about agents and tools make sure to read the [introductory guide](../index). This page -contains the API docs for the underlying classes. +要了解更多关于智能体和工具的信息，请务必阅读[入门指南](../index)。本页面包含底层类的 API 文档。 -## Tools +## 工具 ### load_tool @@ -43,40 +42,51 @@ contains the API docs for the underlying classes. [[autodoc]] launch_gradio_demo -## Default tools +## 默认工具 ### PythonInterpreterTool [[autodoc]] PythonInterpreterTool +### FinalAnswerTool + +[[autodoc]] FinalAnswerTool + +### UserInputTool + +[[autodoc]] UserInputTool + ### DuckDuckGoSearchTool [[autodoc]] DuckDuckGoSearchTool +### GoogleSearchTool + +[[autodoc]] GoogleSearchTool + ### VisitWebpageTool [[autodoc]] VisitWebpageTool -## ToolCollection +### SpeechToTextTool + +[[autodoc]] SpeechToTextTool + +## 工具集合 [[autodoc]] ToolCollection -## Agent Types +## 智能体类型 -Agents can handle any type of object in-between tools; tools, being completely multimodal, can accept and return -text, image, audio, video, among other types. In order to increase compatibility between tools, as well as to -correctly render these returns in ipython (jupyter, colab, ipython notebooks, ...), we implement wrapper classes -around these types. +智能体可以处理工具之间的任何类型的对象；工具是完全多模态的，可以接受和返回文本、图像、音频、视频以及其他类型的对象。为了增加工具之间的兼容性，以及正确呈现在 ipython（jupyter、colab、ipython notebooks 等）中的返回结果，我们为这些类型实现了包装类。 -The wrapped objects should continue behaving as initially; a text object should still behave as a string, an image -object should still behave as a `PIL.Image`. +被包装的对象应该继续保持其初始行为；例如，一个文本对象应继续表现为字符串，一个图像对象应继续表现为 `PIL.Image`。 -These types have three specific purposes: +这些类型有三个特定的用途： -- Calling `to_raw` on the type should return the underlying object -- Calling `to_string` on the type should return the object as a string: that can be the string in case of an `AgentText` - but will be the path of the serialized version of the object in other instances -- Displaying it in an ipython kernel should display the object correctly +- 调用 `to_raw` 方法时，应返回底层对象 +- 调用 `to_string` 方法时，应将对象转换为字符串：对于 `AgentText` 类型，可以直接返回字符串；对于其他实例，则返回对象序列化版本的路径 +- 在 ipython 内核中显示时，应正确显示对象 ### AgentText