[Ready] Translate tutorial into Chinese (#49)

Co-authored-by: ZiTao-Li <[email protected]> Co-authored-by: rayrayraykk <[email protected]> Co-authored-by: panxuchen.pxc <[email protected]> Co-authored-by: qbc <[email protected]>
modelscope · Mar 12, 2024 · 0b4bf85 · 0b4bf85
1 parent 473d6c6
commit 0b4bf85
Show file tree

Hide file tree

Showing 87 changed files with 3,960 additions and 764 deletions.
diff --git a/.github/workflows/sphinx_docs.yml b/.github/workflows/sphinx_docs.yml
@@ -33,7 +33,7 @@ jobs:
       name: Build Documentation
       run: |
         cd docs/sphinx_doc
-        make clean html
+        make clean all
     - name: Upload Documentation
       uses: actions/upload-artifact@v3
       with:

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -28,6 +28,7 @@ repos:
             (?x)(
                 pb2\.py$
                 | grpc\.py$
+                | ^docs
             )
         args: [ --disallow-untyped-defs,
                 --disallow-incomplete-defs,

diff --git a/docs/sphinx_doc/Makefile b/docs/sphinx_doc/Makefile
@@ -1,20 +1,32 @@
-# Minimal makefile for Sphinx documentation
-#
+# Makefile
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = AgentScope-Doc
+ASSETSDIR     = assets
+BUILDDIR      = build/html
+SOURCEDIR_EN  = en/source
+BUILDDIR_EN   = build/html/en
+SOURCEDIR_ZH  = zh_CN/source
+BUILDDIR_ZH   = build/html/zh_CN
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+# English document
+en:
+	@$(SPHINXBUILD) -b html "$(SOURCEDIR_EN)" "$(BUILDDIR_EN)"
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR_EN)"
 
-.PHONY: help Makefile
+# Chinese document
+zh_CN:
+	@$(SPHINXBUILD) -b html "$(SOURCEDIR_ZH)" "$(BUILDDIR_ZH)"
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR_ZH)"
+
+index:
+	@cp "$(ASSETSDIR)/redirect.html" "$(BUILDDIR)/index.html"
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR_EN)" "$(BUILDDIR_EN)" $(O)
+
+all: en zh_CN index
+
+.PHONY: all en zh_CN index
diff --git a/docs/sphinx_doc/assets/redirect.html b/docs/sphinx_doc/assets/redirect.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta http-equiv="refresh" content="0; url=en/index.html" />
+    <title>AgentScope Documentation</title>
+  </head>
+  <body>
+    <p>Redirecting to English documentation...</p>
+    <p>If you are not redirected, <a href="en/index.html">click here</a>.</p>
+  </body>
+</html>
diff --git a/docs/sphinx_doc/en/source/_static/custom.css b/docs/sphinx_doc/en/source/_static/custom.css
@@ -0,0 +1,4 @@
+.language-selector a {
+    color: white;
+    width: 20px;
+}
diff --git a/docs/sphinx_doc/en/source/_templates/language_selector.html b/docs/sphinx_doc/en/source/_templates/language_selector.html
@@ -0,0 +1,5 @@
+<!-- language_selector.html -->
+<div class="language-selector">
+    <a href="{{ pathto('../en/index') }}">English</a></li> |
+    <a href="{{ pathto('../zh_CN/index') }}">中文</a></li>
+</div>
diff --git a/docs/sphinx_doc/en/source/_templates/layout.html b/docs/sphinx_doc/en/source/_templates/layout.html
@@ -0,0 +1,3 @@
+<!-- layout.html -->
+{% extends "!layout.html" %} {% block sidebartitle %} {{ super() }} {% include
+"language_selector.html" %} {% endblock %}
diff --git a/docs/sphinx_doc/source/agentscope.agents.rst → ...phinx_doc/en/source/agentscope.agents.rst b/docs/sphinx_doc/source/agentscope.agents.rst → ...phinx_doc/en/source/agentscope.agents.rst
diff --git a/docs/sphinx_doc/source/agentscope.memory.rst → ...phinx_doc/en/source/agentscope.memory.rst b/docs/sphinx_doc/source/agentscope.memory.rst → ...phinx_doc/en/source/agentscope.memory.rst
diff --git a/docs/sphinx_doc/source/agentscope.models.rst → ...phinx_doc/en/source/agentscope.models.rst b/docs/sphinx_doc/source/agentscope.models.rst → ...phinx_doc/en/source/agentscope.models.rst
diff --git a/...phinx_doc/source/agentscope.pipelines.rst → ...nx_doc/en/source/agentscope.pipelines.rst b/...phinx_doc/source/agentscope.pipelines.rst → ...nx_doc/en/source/agentscope.pipelines.rst
diff --git a/docs/sphinx_doc/source/agentscope.rpc.rst → docs/sphinx_doc/en/source/agentscope.rpc.rst b/docs/sphinx_doc/source/agentscope.rpc.rst → docs/sphinx_doc/en/source/agentscope.rpc.rst
diff --git a/docs/sphinx_doc/source/agentscope.rst → docs/sphinx_doc/en/source/agentscope.rst b/docs/sphinx_doc/source/agentscope.rst → docs/sphinx_doc/en/source/agentscope.rst
diff --git a/...ource/agentscope.service.execute_code.rst → ...ource/agentscope.service.execute_code.rst b/...ource/agentscope.service.execute_code.rst → ...ource/agentscope.service.execute_code.rst
diff --git a/...nx_doc/source/agentscope.service.file.rst → ...doc/en/source/agentscope.service.file.rst b/...nx_doc/source/agentscope.service.file.rst → ...doc/en/source/agentscope.service.file.rst
diff --git a/...c/source/agentscope.service.retrieval.rst → ...n/source/agentscope.service.retrieval.rst b/...c/source/agentscope.service.retrieval.rst → ...n/source/agentscope.service.retrieval.rst
diff --git a/.../sphinx_doc/source/agentscope.service.rst → ...hinx_doc/en/source/agentscope.service.rst b/.../sphinx_doc/source/agentscope.service.rst → ...hinx_doc/en/source/agentscope.service.rst
diff --git a/...c/source/agentscope.service.sql_query.rst → ...n/source/agentscope.service.sql_query.rst b/...c/source/agentscope.service.sql_query.rst → ...n/source/agentscope.service.sql_query.rst
diff --git a/...ce/agentscope.service.text_processing.rst → ...ce/agentscope.service.text_processing.rst b/...ce/agentscope.service.text_processing.rst → ...ce/agentscope.service.text_processing.rst
diff --git a/.../source/agentscope.service.web_search.rst → .../source/agentscope.service.web_search.rst b/.../source/agentscope.service.web_search.rst → .../source/agentscope.service.web_search.rst
diff --git a/docs/sphinx_doc/source/agentscope.utils.rst → ...sphinx_doc/en/source/agentscope.utils.rst b/docs/sphinx_doc/source/agentscope.utils.rst → ...sphinx_doc/en/source/agentscope.utils.rst
diff --git a/docs/sphinx_doc/source/agentscope.web.rst → docs/sphinx_doc/en/source/agentscope.web.rst b/docs/sphinx_doc/source/agentscope.web.rst → docs/sphinx_doc/en/source/agentscope.web.rst
@@ -4,8 +4,7 @@ Web UI package
 app module
 -----------------------------
 
-.. automodule:: agentscope.web.app
+.. automodule:: agentscope.web._app
    :members:
-   :undoc-members: gradio_groupchat
    :show-inheritance:
 
diff --git a/docs/sphinx_doc/source/conf.py → docs/sphinx_doc/en/source/conf.py b/docs/sphinx_doc/source/conf.py → docs/sphinx_doc/en/source/conf.py
@@ -19,6 +19,8 @@
 
 # -- Project information -----------------------------------------------------
 
+language = "en"
+
 project = "AgentScope"
 copyright = "2024, Alibaba Tongyi Lab"
 author = "SysML team of Alibaba Tongyi Lab"
@@ -71,3 +73,7 @@
     ".rst": "restructuredtext",
     ".md": "markdown",
 }
+
+html_css_files = [
+    "custom.css",
+]
diff --git a/docs/sphinx_doc/source/index.rst → docs/sphinx_doc/en/source/index.rst b/docs/sphinx_doc/source/index.rst → docs/sphinx_doc/en/source/index.rst
diff --git a/docs/sphinx_doc/en/source/tutorial/101-agentscope.md b/docs/sphinx_doc/en/source/tutorial/101-agentscope.md
@@ -0,0 +1,116 @@
+(101-agentscope-en)=
+
+# About AgentScope
+
+In this tutorial, we will provide an overview of AgentScope by answering
+several questions, including what's AgentScope, what can AgentScope provide,
+and why we should choose AgentScope. Let's get started!
+
+## What is AgentScope?
+
+AgentScope is a developer-centric multi-agent platform, which enables
+developers to build their LLM-empowered multi-agent applications with less
+effort.
+
+With the advance of large language models, developers are able to build
+diverse applications.
+In order to connect LLMs to data and services and solve complex tasks,
+AgentScope provides a series of development tools and components for ease of
+development.
+It features
+
+- **usability**,
+- **robustness**, and
+- **the support of multi-modal data** and
+- **distributed deployment**.
+
+## Key Concepts
+
+### Message
+
+Message is a carrier of information (e.g. instructions, multi-modal
+data, and dialogue). In AgentScope, message is a Python dict subclass
+with `name` and `content` as necessary fields, and `url` as an optional
+field referring to additional resources.
+
+### Agent
+
+Agent is an autonomous entity capable of interacting with environment and
+agents, and taking actions to change the environment. In AgentScope, an
+agent takes message as input and generates corresponding response message.
+
+### Service
+
+Service refers to the functional APIs that enable agents to perform
+specific tasks. In AgentScope, services are categorized into model API
+services, which are channels to use the LLMs, and general API services,
+which provide a variety of tool functions.
+
+### Workflow
+
+Workflow represents ordered sequences of agent executions and message
+exchanges between agents, analogous to computational graphs in TensorFlow,
+but with the flexibility to accommodate non-DAG structures.
+
+## Why AgentScope?
+
+**Exceptional usability for developers.**
+AgentScope provides high usability for developers with flexible syntactic
+sugars, ready-to-use components, and pre-built examples.
+
+**Robust fault tolerance for diverse models and APIs.**
+AgentScope ensures robust fault tolerance for diverse models, APIs, and
+allows developers to build customized fault-tolerant strategies.
+
+**Extensive compatibility for multi-modal application.**
+AgentScope supports multi-modal data (e.g., files, images, audio and videos)
+in both dialog presentation, message transmission and data storage.
+
+**Optimized efficiency for distributed multi-agent operations.** AgentScope
+introduces an actor-based distributed mechanism that enables centralized
+programming of complex distributed workflows, and automatic parallel
+optimization.
+
+## How is AgentScope designed?
+
+The architecture of AgentScope comprises three hierarchical layers. The
+layers provide supports for multi-agent applications from different levels,
+including elementary and advanced functionalities of a single agent
+(**utility layer**), resources and runtime management (**manager and wrapper
+layer**), and agent-level to workflow-level programming interfaces (**agent
+layer**). AgentScope introduces intuitive abstractions designed to fulfill
+the diverse functionalities inherent to each layer and simplify the
+complicated interlayer dependencies when building multi-agent systems.
+Furthermore, we offer programming interfaces and default mechanisms to
+strengthen the resilience of multi-agent systems against faults within
+different layers.
+
+## AgentScope Code Structure
+
+```bash
+AgentScope
+├── src
+│   ├── agentscope
+│   |   ├── agents               # Core components and implementations pertaining to agents.
+│   |   ├── memory               # Structures for agent memory.
+│   |   ├── models               # Interfaces for integrating diverse model APIs.
+│   |   ├── pipeline             # Fundamental components and implementations for running pipelines.
+│   |   ├── rpc                  # Rpc module for agent distributed deployment.
+│   |   ├── service              # Services offering functions independent of memory and state.
+|   |   ├── web                  # WebUI used to show dialogs.
+│   |   ├── utils                # Auxiliary utilities and helper functions.
+│   |   ├── message.py           # Definitions and implementations of messaging between agents.
+│   |   ├── prompt.py            # Prompt engineering module for model input.
+│   |   ├── ... ..
+│   |   ├── ... ..
+├── scripts                      # Scripts for launching local Model API
+├── examples                     # Pre-built examples of different applications.
+├── docs                         # Documentation tool for API reference.
+├── tests                        # Unittest modules for continuous integration.
+├── LICENSE                      # The official licensing agreement for AgentScope usage.
+└── setup.py                     # Setup script for installing.
+├── ... ..
+└── ... ..
+```
+
+[[Return to the top]](#101-agentscope)
diff --git a/...x_doc/source/tutorial/101-installation.md → ...oc/en/source/tutorial/102-installation.md b/...x_doc/source/tutorial/101-installation.md → ...oc/en/source/tutorial/102-installation.md
@@ -1,12 +1,12 @@
-(101-installation)=
+(102-installation-en)=
 
 # Installation
 
 To install AgentScope, you need to have Python 3.9 or higher installed. We recommend setting up a new virtual environment specifically for AgentScope:
 
-### Create a Virtual Environment
+## Create a Virtual Environment
 
-#### Using Conda
+### Using Conda
 
 If you're using Conda as your package and environment management tool, you can create a new virtual environment with Python 3.9 using the following commands:
 
@@ -18,7 +18,7 @@ conda create -n agentscope python=3.9
 conda activate agentscope
 ```
 
-#### Using Virtualenv
+### Using Virtualenv
 
 Alternatively, if you prefer `virtualenv`, you can install it first (if it's not already installed) and then create a new virtual environment as shown:
 
@@ -33,9 +33,9 @@ virtualenv agentscope --python=python3.9
 source agentscope/bin/activate  # On Windows use `agentscope\Scripts\activate`
 ```
 
-### Installing AgentScope
+## Installing AgentScope
 
-#### Install with Pip
+### Install with Pip
 
 If you prefer to install AgentScope from Pypi, you can do so easily using `pip`:
 
@@ -46,7 +46,7 @@ pip install agentscope
 pip install agentscope[distribute]  # On Mac use `pip install agentscope\[distribute\]`
 ```
 
-#### Install from Source
+### Install from Source
 
 For users who prefer to install AgentScope directly from the source code, follow these steps to clone the repository and install the platform in editable mode:
 
@@ -65,4 +65,4 @@ pip install -e .[distribute]  # On Mac use `pip install -e .\[distribute\]`
 
 **Note**: The `[distribute]` option installs additional dependencies required for distributed applications. Remember to activate your virtual environment before running these commands.
 
-[[Return to the top]](#installation)
+[[Return to the top]](#102-installation-en)
diff --git a/...sphinx_doc/source/tutorial/103-example.md → ...inx_doc/en/source/tutorial/103-example.md b/...sphinx_doc/source/tutorial/103-example.md → ...inx_doc/en/source/tutorial/103-example.md
@@ -1,19 +1,34 @@
-(103-example)=
+(103-start-en)=
 
-# Getting Started with a Simple Example
+# Quick Start
 
-AgentScope is a versatile platform for building and running multi-agent applications. We provide various pre-built examples that will help you quickly understand how to create and use multi-agent for various applications. In this tutorial, you will learn how to set up a **simple agent-based interaction**.
+AgentScope is designed with a flexible communication mechanism.
+In this tutorial, we will introduce the basic usage of AgentScope via a
+simple standalone conversation between two agents (e.g. user and assistant
+agents).
 
-## Step1: Prepare Model Configs
+## Step1: Prepare Model
 
-Agent is the basic composition and communication unit in AgentScope. To initialize a model-based agent, you need to prepare your configs for avaliable models. AgentScope supports a variety of APIs for pre-trained models. Here is a table outlining the supported APIs and the type of arguments required for each:
+AgentScope decouples the deployment and invocation of models to better build multi-agent applications.
 
-|   Model Usage               | Model Type Argument in AgentScope | Supported APIs                                                              |
-| --------------------------- | --------------------------------- |-----------------------------------------------------------------------------|
-| Text generation             | `openai`                          | Standard *OpenAI* chat API, FastChat and vllm                               |
-| Image generation            | `openai_dall_e`                   | *DALL-E* API for generating images                                          |
-| Embedding                   | `openai_embedding`                | API for text embeddings                                                     |
-| General usages in POST      | `post_api`                        | *Huggingface* and *ModelScope* Inference API, and other customized post API |
+In terms of model deployment, users can use third-party model services such
+as OpenAI API, HuggingFace/ModelScope Inference API, and can also quickly
+deploy local open-source model services through the [scripts]
+(<https://github.com/modelscope/agentscope/blob/main/scripts/README.md>) in
+the repository. Currently, we support building basic model services quickly
+using Flask with Transformers (or ModelScope), and also support deploying
+local model services through FastChat and vllm inference engines.
+
+While in terms of model invocation, AgentScope provides a `ModelWrapper` class to encapsulate OpenAI API and RESTful Post Request calls.
+Currently, the supported OpenAI APIs include Chat, Image generation, and Embedding.
+Users can specify the model service by setting different model configs.
+
+|   Model Usage               | Supported APIs                                                              |
+| --------------------------- |-----------------------------------------------------------------------------|
+| Text generation             | Standard *OpenAI* chat API, FastChat and vllm                               |
+| Image generation            | *DALL-E* API for generating images                                          |
+| Embedding                   | API for text embeddings                                                     |
+| General usages in POST      | *Huggingface* and *ModelScope* Inference API, and other customized post API |
 
 Each API has its specific configuration requirements. For example, to configure an OpenAI API, you would need to fill out the following fields in the model config in a dict, a yaml file or a json file:
 
@@ -27,9 +42,9 @@ model_config = {
 }
 ```
 
-For open-source models, we support integration with various model interfaces such as HuggingFace, ModelScope, FastChat, and vllm. You can find scripts on deploying these services in the `scripts` directory, and we defer the detailed instructions to [[Using Different Model Sources with Model API]](203-model).
+For open-source models, we support integration with various model interfaces such as HuggingFace, ModelScope, FastChat, and vllm. You can find scripts on deploying these services in the `scripts` directory, and we defer the detailed instructions to [[Using Different Model Sources with Model API]](#203-model).
 
-You can register your configuration by calling AgentScope's initilization method as follow. Besides, you can also load more than one config by calling init mutliple times.
+You can register your configuration by calling AgentScope's initialization method as follow. Besides, you can also load more than one config by calling init multiple times.
 
 ```python
 import agentscope
@@ -99,4 +114,4 @@ while x is None or x.content != "exit":
 
 For more details about how to utilize pipelines for complex agent interactions, please refer to [[Agent Interactions: Dive deeper into Pipelines and Message Hub]](202-pipeline).
 
-[[Return to the top]](#getting-started-with-a-simple-example)
+[[Return to the top]](#103-start-en)
diff --git a/...sphinx_doc/source/tutorial/104-usecase.md → ...inx_doc/en/source/tutorial/104-usecase.md b/...sphinx_doc/source/tutorial/104-usecase.md → ...inx_doc/en/source/tutorial/104-usecase.md
@@ -1,4 +1,4 @@
-(104-usecase)=
+(104-usecase-en)=
 
 # Crafting Your First Application
 
@@ -12,19 +12,7 @@ Let the adventure begin to unlock the potential of multi-agent applications with
 
 ## Getting Started
 
-Firstly, ensure that you have installed and configured AgentScope properly. Besides, we will involve the basic concepts of `Model API`,  `Agent`, `Msg`, and `Pipeline,` as described in [Tutorial-Concept](102-concepts). The overview of this tutorial is shown below:
-
-- [Crafting Your First Application](#crafting-your-first-application)
-  - [Getting Started](#getting-started)
-    - [Step 1: Prepare Model API and Set Model Configs](#step-1-prepare-model-api-and-set-model-configs)
-    - [Step 2: Define the Roles of Each Agent](#step-2-define-the-roles-of-each-agent)
-    - [Step 3: Initialize AgentScope and the Agents](#step-3-initialize-agentscope-and-the-agents)
-    - [Step 4: Set Up the Game Logic](#step-4-set-up-the-game-logic)
-      - [Leverage Pipeline and MsgHub](#leverage-pipeline-and-msghub)
-      - [Implement Werewolf Pipeline](#implement-werewolf-pipeline)
-    - [Step 5: Run the Application](#step-5-run-the-application)
-  - [Next step](#next-step)
-  - [Other Example Applications](#other-example-applications)
+Firstly, ensure that you have installed and configured AgentScope properly. Besides, we will involve the basic concepts of `Model API`,  `Agent`, `Msg`, and `Pipeline,` as described in [Tutorial-Concept](101-agentscope).
 
 **Note**: all the configurations and code for this tutorial can be found in `examples/werewolf`.
 
@@ -327,4 +315,4 @@ Now you've grasped how to conveniently set up a multi-agent application with Age
 - Example of Distributed Agents: [examples/Distributed Agents](https://github.com/modelscope/agentscope/tree/main/examples/distributed_agents/README.md)
 - ...
 
-[[Return to the top]](#crafting-your-first-application)
+[[Return to the top]](#104-usecase-en)