diff --git a/docs/sphinx_doc/source/tutorial/zh/208-distribute.md b/docs/sphinx_doc/source/tutorial/zh/208-distribute.md new file mode 100644 index 000000000..7a4707885 --- /dev/null +++ b/docs/sphinx_doc/source/tutorial/zh/208-distribute.md @@ -0,0 +1,133 @@ +# 分布式运行 + +AgentScope 完全基于分布式设计,一个应用程序中的不同 Agent 实例可以部署在不同的机器上并行运行。本教程将介绍 AgentScope 分布式的特点和分布式部署方法。 + +## 特点 + +### 每个 “Agent” 都是一个“Actor” + +[Actor 模式](https://en.wikipedia.org/wiki/Actor_model)是大规模分布式系统中广泛使用的编程范式,AgentScope 也是基于该范式。每个 Agent 都是一个 Actor,并通过消息与其他 Agent 交互。消息的流转暗示了 Agent 的执行顺序。每个 Agent 都有一个 `reply` 方法,它消费一条消息并生成另一条消息,生成的消息可以发送给其他 Agent。例如,下面的图表显示了多个 Agent 的工作流程。`A` ~ `F` 都是 Agent,箭头代表消息。 + +```{mermaid} +graph LR; +A-->B +A-->C +B-->D +C-->D +E-->F +D-->F +``` + +其中,`B` 和 `C` 可以在接收到来自 `A` 的消息后同时启动执行,而 `E` 可以立即运行,无需等待 `A`、`B`、`C` 和 `D`。 +通过将每个 Agent 实现为一个 Actor, Agent 将自动等待其输入 Msg 准备好后开始执行 `reply` 方法,并且如果多个 Agent 的输入消息准备就绪,它们也可以同时自动执行 `reply`,这避免了复杂的并行控制。 + +### 集中式编写,分布式运行 + +在 AgentScope 中,可以在同一台或多台不同的机器上将 Agent 启动为单独的进程。但应用程序开发者不需要关心这些 Agent 在哪里运行;您只需使用面向过程式编程范式在主进程中编写应用程序代码。AgentScope 将帮助您将任务转换为分布式版本。下面是一段应用程序代码,其中 `A`、`B` 和 `C` 运行在不同的机器上。 + +``` +x = A() +y = B(x) +z = C(x) +``` + +尽管这段代码看起来是完全顺序执行的,但 AgentScope 将自动检测您代码中的潜在并行性,如下面的流图所示,这意味着 `C` 将不会等待 `B` 完成就开始执行。 + +```{mermaid} +graph LR; +A-->B +A-->C +``` + +## 简易的分布式部署 + +请按照以下步骤分布式部署您的应用程序。 + +### 转换 Agent + +`AgentBase` 提供了 `to_dist` 方法将该 Agent 自身转换为分布式版本。 +`to_dist` 需要几个参数。 + +- `host`: 运行 Agent 的机器的主机名或 IP 地址,默认为 `localhost`。 +- `port`: 此 Agent 的 RPC 服务器端口,默认为 `80`。 +- `launch_server`: 是否在本地启动 RPC 服务器,默认为 `True`。 +- `local_mode`: 如果所有 Agent 都在同一台机器上运行,则设置为 `True`,默认为 `True`。 +- `lazy_launch`: 如果设置为 `True`,则只在调用 Agent 时启动服务器。 + +> `to_dist` 方法基于 [gRPC](https://grpc.io/). 当设置 'launch_server' 为 `True` 时,它将启动一个 gRPC 服务器进程,并将原始 Agent 转移到新进程中运行。 + +### Run in multi-process mode + +AgentScope 支持在多进程模式下部署,其中每个 Agent 是应用程序主进程的子进程,所有 Agent 都在同一台机器上运行。 +其使用方式与单进程模式完全相同,您只需要在初始化后调用 `to_dist` 方法。 + +假设您有两个 class, `A` 和 `B`,它们都继承自 `AgentBase`。 + +```python +# 导入依赖包 + +a = A( + name="A", + ..., +).to_dist() +b = B( + name="B", + ..., +).to_dist() + +x = None +while x is None or x.content != 'exit': + x = a(x) + x = b(x) +``` + +### 在多台机器上运行 + +AgentScope 也支持在多台机器上运行 Agent。在这种情况下,您需要分别启动 Agent。例如,您可以使用以下代码在 IP 地址为 `ip_a` 的机器上启动 Agent A。 + +```python +# 导入依赖包 + +server_a = RpcAgentServerLauncher( + agent_class=A, + agent_kwargs={ + "name": "A" + ... + }, + host=ip_a, + port=12001, +) +server_a.launch() +server_a.wait_until_terminate() +``` + +同样,您可以在 IP 地址为 `ip_b` 的机器上启动 Agent B。 +请确保两台机器可以使用 IP 地址相互访问。 + +```python +# 导入依赖包 + +a = A( + name="A", + ... +).to_dist( + host=ip_a, + port=12001, + launch_server=False, +) +b = B( + name="B", + ... +).to_dist( + host=ip_b, + port=12002, + launch_server=False, +) + +x = None +while x is None or x.content != 'exit': + x = a(x) + x = b(x) +``` + +[[回到顶部]](#分布式运行) diff --git a/docs/sphinx_doc/source/tutorial/zh/301-community.md b/docs/sphinx_doc/source/tutorial/zh/301-community.md new file mode 100644 index 000000000..a59323515 --- /dev/null +++ b/docs/sphinx_doc/source/tutorial/zh/301-community.md @@ -0,0 +1,34 @@ +(301-community)= + +# 加入 AgentScope 社区 + +加入 AgentScope 社区可以让您与其他用户和开发者建立联系。您可以分享见解、提问、并及时了解最新的进展和有趣的 Multi-Agent 应用程序。以下是加入我们的方法: + +## GitHub + +- **点赞并关注 AgentScope 仓库:** 通过点星和关注 [AgentScope 仓库](https://github.com/modelscope/agentscope) 以表示支持并随时了解我们的进展. +- **提交问题和拉取请求:** 如果您遇到任何问题或有建议,请向相关仓库提交问题。我们也欢迎拉取请求以修复错误、改进或添加新功能。 + +## Discord + +- **加入我们的 Discord:** 实时与 AgentScope 社区合作。在 [Discord](https://discord.gg/eYMpfnkG8h) 上参与讨论,寻求帮助,并分享您的经验和见解。. + +## 钉钉 (DingTalk) + +- **在钉钉上联系:** 加入我们的钉钉群,随时了解有关 AgentScope 的新闻和更新。 + + 扫描下方的二维码加入钉钉群: + + AgentScope-dingtalk + + 我们的钉钉群邀请链接: [AgentScope 钉钉群](https://qr.dingtalk.com/action/joingroup?code=v1,k1,20IUyRX5XZQ2vWjKDsjvI9dhcXjGZi3bq1pFfDZINCM=&_dt_no_comment=1&origin=11) + +## 微信 + +扫描下方的二维码加入微信: AgentScope-wechat + +--- + +我们欢迎所有对 AgentScope 感兴趣的人加入我们的社区,并为平台的增长做出贡献! + +[[Return to the top]](#joining-the-agentscope-community) diff --git a/docs/sphinx_doc/source/tutorial/zh/302-contribute.md b/docs/sphinx_doc/source/tutorial/zh/302-contribute.md new file mode 100644 index 000000000..9cfd89ab3 --- /dev/null +++ b/docs/sphinx_doc/source/tutorial/zh/302-contribute.md @@ -0,0 +1,70 @@ +(302-contribute)= + +# 为AgentScope做贡献 + +我们的社区因其成员的多样化思想和贡献而兴旺发展。无论是修复一个错误,添加一个新功能,改进文档,还是添加示例,我们都欢迎您的帮助。以下是您做出贡献的方法: + +## 报告错误和提出新功能 + +您发现了一个错误或者有一个功能请求吗?请首先检查问题跟踪器,看看它是否已经被报告。如果没有,随时可以开设一个新的问题。包含尽可能多的细节: + +- 简明扼要的标题 +- 清晰地描述问题 +- 提供重现问题的步骤 +- 提供所使用的 AgentScope 版本 +- 提供所有相关代码片段或错误信息 + +## 对代码库做出贡献 + +### Fork 和 Clone 仓库 + +要处理一个问题或新功能,首先要 Fork AgentScope 仓库,然后将你的 Fork 克隆到本地。 + +```bash +git clone https://github.com/your-username/AgentScope.git +cd AgentScope +``` + +### 创建一个新分支 + +为您的工作创建一个新分支。这有助于保持拟议更改的组织性,并与 `main` 分支分离。 + +```bash +git checkout -b your-feature-branch-name +``` + +### 做出修改 + +创建您的新分支后就可以对代码进行修改了。请注意如果您正在解决多个问题或实现多个功能,最好为每个问题或功能创建单独的分支和拉取请求。 + +我们提供了一个开发者版本,与官方版本相比,它附带了额外的 pre-commit 钩子以执行格式检查: + +```bash +# 安装开发者版本 +pip install -e .[dev] +# 安装 pre-commit 钩子 +pre-commit install +``` + +### 提交您的修改 + +修改完成之后就是提交它们的时候了。请提供清晰而简洁的提交信息,以解释您的修改内容。 + +```bash +git add -U +git commit -m "修改内容的简要描述" +``` + +运行时您可能会收到 `pre-commit` 给出的错误信息。请根据错误信息修改您的代码然后再次提交。 + +### 提交 Pull Request + +当您准备好您的修改分支后,向 AgentScope 的 `main` 分支提交一个 Pull Request。在您的Pull Request 描述中,解释您所做的修改以及其他相关的信息。 + +我们将审查您的 Pull Request。这个过程可能涉及一些讨论以及额外的代码修改。 + +### 代码审查 + +等待我们审核您的 Pull Request。我们可能会提供一些更改或改进建议。请留意您的 GitHub 通知,并对反馈做出响应。 + +[[Return to the top]](#为AgentScope做贡献)