Skip to content

Commit

Permalink
Updating sections as well as fixing WeChat QR Code (#131)
Browse files Browse the repository at this point in the history 
* Update README-CN.md

* Fixing QR code of wechat

* Update README-CN.md

* Update README-CN.md

* Update README-CN.md

* Update README-CN.md

* Update README-CN.md
  • Loading branch information
@cyfyifanchen
cyfyifanchen authored Jul 30, 2024
1 parent fb2f8da commit b5acb09
Showing 1 changed file with 144 additions and 129 deletions.
273 changes: 144 additions & 129 deletions docs/readmes/README-CN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,9 @@
[![Issues closed](https://img.shields.io/github/issues-search?query=repo%3Arte-design%2Fastra.ai%20is%3Aclosed&label=issues%20closed&labelColor=green&color=green)](https://github.com/rte-design/ASTRA.ai/issues)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/rte-design/ASTRA.ai/pulls)
[![GitHub license](https://img.shields.io/badge/License-Apache_2.0-blue.svg?labelColor=%20%239b8afb&color=%20%237a5af8)](https://github.com/rte-design/ASTRA.ai/blob/main/LICENSE)
[![WeChat](https://img.shields.io/badge/WeChat-WeChat_Group-%2307C160?logo=wechat)](https://github.com/rte-design/ASTRA.ai/issues/125)

[![](https://dcbadge.vercel.app/api/server/VnPftUzAMJ)](https://discord.gg/VnPftUzAMJ)
[![Discord](https://dcbadge.vercel.app/api/server/VnPftUzAMJ)](https://discord.gg/VnPftUzAMJ)

[![GitHub watchers](https://img.shields.io/github/watchers/rte-design/astra.ai?style=social&label=Watch)](https://GitHub.com/rte-design/astra.ai/watchers/?WT.mc_id=academic-105485-koreyst)
[![GitHub forks](https://img.shields.io/github/forks/rte-design/astra.ai?style=social&label=Fork)](https://GitHub.com/rte-design/astra.ai/network/?WT.mc_id=academic-105485-koreyst)
Expand All @@ -21,211 +22,225 @@

<div align="center">

[超低延迟](./docs/astra-architecture.md)
[低延迟](./docs/astra-architecture.md)
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
[超多模态](./docs/astra-architecture.md#astra-extension)
[多模态](./docs/astra-architecture.md#astra-extension)
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
[超高可配](./docs/astra-architecture.md#-astra-extension-store)

🎉 简单易用，丝滑体验，创建属于这个时代的 AI Agents 🎉
[高可配](./docs/astra-architecture.md#-astra-extension-store)

</div>

## Voice Agent Showcase

[ASTRA Voice Agent](https://theastra.ai)

感谢 ASTRA 的多模态能力，这里搭建的 Voice Agent 速度流畅，体验丝滑。

[![Showcase ASTRA Voice Agent](https://github.com/rte-design/ASTRA.ai/raw/main/images/astra-voice-agent.gif)](https://theastra.ai)

<h3>点星收藏</h3>

我们更新频繁，不想错过的话，请给我们的 repo 点星，以便获得第一时间的更新.
## 项目示例 - The voice agent

![ASTRA star us gif](https://github.com/rte-design/ASTRA.ai/raw/main/images/star-the-repo-confetti-higher-quality.gif)
[示例项目](https://theastra.ai)是通过 ASTRA 搭建出来的 voice agent, 展示了多模态，低延迟的能力。

### 本地运行 Agent
[![展示ASTRA语音助手](https://github.com/rte-design/ASTRA.ai/raw/main/images/astra-voice-agent.gif)](https://theastra.ai)

当然，我们更欢迎您在本地试玩我们的 Voice Agent， 这里有一个 Docker 镜像，您可以在 macOS 和 Windows 上构建并运行该代理。
<br>
<h2>如何在本地搭建 voice agent</h2>

开始之前，请确保您拥有：
#### 先决条件

- Agora App ID and App 证书([详细指南](https://docs.agora.io/en/video-calling/get-started/manage-agora-account?platform=web))
- Azure's [speech-to-text](https://azure.microsoft.com/en-us/products/ai-services/speech-to-text) and [text-to-speech](https://azure.microsoft.com/en-us/products/ai-services/text-to-speech) API keys
- [OpenAI](https://openai.com/index/openai-api/) API key
- Agora App ID 和 App Certificate（[点击此处了解详情](https://docs.agora.io/en/video-calling/get-started/manage-agora-account?platform=web)）
- Azure 的 [STT](https://azure.microsoft.com/en-us/products/ai-services/speech-to-text) 和 [TTS](https://azure.microsoft.com/en-us/products/ai-services/text-to-speech) API 密钥
- [OpenAI](https://openai.com/index/openai-api/) API 密钥
- [Docker](https://www.docker.com/)

```shell
# run the pre-built agent image
docker run --restart=always -itd -p 8080:8080 \
-v /tmp:/tmp \
-e AGORA_APP_ID=<your_agora_appid> \
-e AGORA_APP_CERTIFICATE=<your_agora_app_certificate> \
-e AZURE_STT_KEY=<your_azure_stt_key> \
-e AZURE_STT_REGION=<your_azure_stt_region> \
-e OPENAI_API_KEY=<your_openai_api_key> \
-e AZURE_TTS_KEY=<your_azure_tts_key> \
-e AZURE_TTS_REGION=<your_azure_tts_region> \
--name astra_agents_server \
agoraio/astra_agents_server:latest
```

这条命令将启动一个运行在 8080 端口的代理服务器。
#### Apple Silicon 上的 Docker 设置
如果您使用的是 Apple Silicon，您需要取消勾选 Docker 的 "Use Rosetta for x86_64/amd64 emulation on apple silicon" 选项，否则服务器将无法正常工作。

### 用 playground 链接您自己的 agent
<div align="center">

您可以使用 Playground 项目来测试刚刚启动的服务器。
![ASTRA Docker Setting](https://github.com/rte-design/ASTRA.ai/raw/main/images/docker-setting.gif)

Playground 项目是基于 NextJS 14 构建的，因此需要 Node 18+ 版本。
</div>

```shell
# set up an .env file
cp ./playground/.env.example ./playground/.env
cd playground
#### 设置 Go 国内代理
如果在国内，我们建议跑下列命令来全局设定国内代理以便快速下载依赖([了解详情](https://goproxy.cn/))。

# install npm dependencies & start
npm i && npm run dev
```
$ go env -w GO111MODULE=on
$ go env -w GOPROXY=https://goproxy.cn,direct
```

🎉 恭喜！您现在已经成功在本地运行了我们的 ASTRA Voice Agent.

</br>

## Agent 定制化

我们的语音代理是一个很好的起点，它使用了以下扩展：

- _agora_rtc_ / [Agora](https://docs.agora.io/en) for RTC transport + VAD + Azure speech-to-text (STT)
- _azure_tts_ / [Azure](https://azure.microsoft.com/en-us/products/ai-services/text-to-speech) for text-to-speech (TTS)
- _openai_chatgpt_ / [OpenAI](https://openai.com/index/openai-api/) for LLM
- _chat_transcriber_ / A utility ext to forward chat logs into channel
- _interrupt_detector_ / A utility ext to help interrupt agent

![](../../images/image-2.png)

### 定制个性化 Agent

您可能希望添加更多的功能，以使代理更适合您的需求。为此，您需要修改扩展的源代码并自行构建代理。

首先需要改动 `manifest.json`:
#### 1. 在 Docker 镜像中构建 agent

```shell
# rename manifest example
```bash
# 从示例文件创建 manifest
cp ./agents/manifest.json.example ./agents/manifest.json
cp ./agents/manifest.json.en.example ./agents/manifest.en.json
cp ./agents/manifest.json.cn.example ./agents/manifest.cn.json

# pull the docker image with dev tools and mount your current folder as workspace
docker run -itd -v $(pwd):/app -w /app -p 8080:8080 --name astra_agents_dev ghcr.io/rte-design/astra_agents_build:0.3.2
# 拉取带有开发工具的 Docker 镜像，并将当前文件夹挂载为工作区
docker run -itd -v $(pwd):/app -w /app -p 8080:8080 --name astra_agents_dev ghcr.io/rte-design/astra_agents_build

# for windows git bash
# docker run -itd -v //$(pwd):/app -w //app -p 8080:8080 --name astra_agents_dev ghcr.io/rte-design/astra_agents_build:0.3.2
# 对于 Windows Git Bash
# docker run -itd -v //$(pwd):/app -w //app -p 8080:8080 --name astra_agents_dev ghcr.io/rte-design/astra_agents_build

# enter docker image
# 进入 Docker 镜像
docker exec -it astra_agents_dev bash

# build agent
# 构建 agent
make build
```

该代码生成一个代理可执行文件。要自定义提示和 OpenAI 参数，请修改 agents/addon/extension/openai_chatgpt/openai_chatgpt.go 源代码。
#### 2. 改动 prompts
上述代码生成了一个代理可执行文件。要自定义提示和 OpenAI 参数，请修改 `agents/addon/extension/openai_chatgpt/openai_chatgpt.go` 中的以下代码：

```go
func defaultOpenaiChatGPTConfig() openaiChatGPTConfig {
return openaiChatGPTConfig{
BaseUrl: "https://api.openai.com/v1",
ApiKey: "",
Model: openai.GPT4o,
Prompt: "You are a voice assistant who talks in a conversational way and can chat with me like my friends. i will speak to you in english or chinese, and you will answer in the corrected and improved version of my text with the language i use. Don't talk like a robot, instead i would like you to talk like real human with emotions. i will use your answer for text-to-speech, so don't return me any meaningless characters. I want you to be helpful, when i'm asking you for advices, give me precise, practical and useful advices instead of being vague. When giving me list of options, express the options in a narrative way instead of bullet points.",
FrequencyPenalty: 0.9,
PresencePenalty: 0.9,
TopP: 1.0,
Temperature: 0.1,
MaxTokens: 512,
Seed: rand.Int(),
ProxyUrl: "",
}
}
```

完成修改后，您可以使用以下命令启动服务器。然后，您可以像之前的步骤一样，使用 ASTRA Voice Agent 在 Playground 进行测试。
#### 3. 启动本地服务器

```shell
通过运行以下终端命令启动服务器：

```bash
# Agora App ID and Agora App Certificate
export AGORA_APP_ID=<your_agora_appid>
export AGORA_APP_CERTIFICATE=<your_agora_app_certificate>
export AZURE_STT_KEY=<your_azure_stt_key>
export AZURE_STT_REGION=<your_azure_stt_region>

# LLM
# OpenAI API key
export OPENAI_API_KEY=<your_openai_api_key>
export QWEN_API_KEY=<your_qwern_api_key>

# Azure STT key and region
export AZURE_STT_KEY=<your_azure_stt_key>
export AZURE_STT_REGION=<your_azure_stt_region>

# TTS
# cosy
export COSY_TTS_KEY=<your_cosy_tts_key>
# if you use AZURE_TTS
# Here are three TTS options, either one will work
# Make sure to comment out the one you don't use

# 1. using Azure
export TTS_VENDOR_CHINESE=azure
export AZURE_TTS_KEY=<your_azure_tts_key>
export AZURE_TTS_REGION=<your_azure_tts_region>

# 2. using ElevenLabs
export TTS_VENDOR_ENGLISH=elevenlabs
export ELEVENLABS_TTS_KEY=<your_elevanlabs_tts_key>

# agent is ready to start on port 8080

# Agent is ready to start on port 8080
make run-server
```

🎉 恭喜你！你已经创建了你的第一个个性化语音代理。我们对你的努力表示赞赏，并期待在 ASTRA 云商店中看到它。如果你能在社区中分享它，我们将不胜感激。
#### 4. 运行 voice agent 界面

<br />
voice agent 界面是基于 NextJS 14 构建的，因此需要 Node 18 或更高版本。

## ASTRA 服务
```bash
# 创建一个本地的环境文件
cd playground
cp .env.example .env

现在让我们来深入了解一下。ASTRA 服务由多种不同编程语言开发的 ASTRA 扩展组成。这些扩展通过图谱相互连接，描述它们的关系并展示数据流动。此外，通过 ASTRA 云商店和 ASTRA 包管理器，扩展的分享和下载变得更加简便。
# 安装依赖
npm install && npm run dev
```

![ASTRA Architecture](../../images/image.png)
#### 5. 验证您定制的 voice agent 🎉

### ASTRA 扩展
在浏览器中打开 `localhost:3000`，您应该能够看到一个与示例项目一样的 voice angent，但是这次是带有定制的 voice agent。

扩展是 ASTRA 框架中的基本组合单元。开发人员可以使用多种编程语言创建扩展，并将它们组合起来构建不同的场景和应用程序。ASTRA 强调跨语言协作，允许使用不同语言编写的扩展在同一应用程序或服务中无缝协同工作。
<br>
<h2>Voice agent 架构</h2>
要进一步探索， voice agent 是一个绝佳的起点。它包含以下扩展功能，其中一些将在不久的将来可以互换使用。请随意选择最适合您需求并最大化 ASTRA 功能的扩展。

例如，如果一个应用程序需要实时通信（RTC）功能和先进的人工智能能力，开发人员可以选择使用 C++ 编写与音频和视频数据处理性能优势相关的 RTC 相关扩展。同时，他们可以使用 Python 开发 AI 扩展，利用其丰富的库和框架进行数据分析和机器学习任务。
| 扩展功能 | 特点 | 描述 |
| ------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| openai_chatgpt | 语言模型 | [ GPT-4o ](https://platform.openai.com/docs/models/gpt-4o), [ GPT-4 Turbo ](https://platform.openai.com/docs/models/gpt-4-turbo-and-gpt-4), [ GPT-3.5 Turbo ](https://platform.openai.com/docs/models/gpt-3-5-turbo) |
| elevenlabs_tts | 文本转语音 | [ElevanLabs 文本转语音](https://elevenlabs.io/) 将文本转换为音频 |
| azure_tts | 文本转语音 | [Azure 文本转语音](https://azure.microsoft.com/en-us/products/ai-services/text-to-speech) 将文本转换为音频 |
| azure_stt | 语音转文本 | [Azure 语音转文本](https://azure.microsoft.com/en-us/products/ai-services/speech-to-text) 将音频转换为文本 |
| chat_transcriber | 转录工具 | 将聊天记录转发到频道的实用工具 |
| agora_rtc | 传输工具 | 由 agora_rtc 提供支持的低延迟传输工具 |
| interrupt_detector | 中断工具 | 帮助中断语音助手的实用工具 |

### 语言支持
<h3>Voice agent 架构图</h3>

截至 2024 年 6 月，我们支持以下语言编写的扩展：
![ASTRAvoice agent架构图](../../images/image-2.png)

- C++
- Golang
- Python (7 月)

开发人员可以灵活选择最适合他们需求的语言，并将其无缝集成到 ASTRA 框架中。
<br>
<h2>搭建无界面的 voice agent</h2>

这段内容详细描述了截至指定日期的 ASTRA 扩展支持的编程语言。
#### 1. 在 Docker 镜像中搭建 voice agent

## 图谱
```
# 从示例文件创建 manifest
cp ./agents/manifest.json.example ./agents/manifest.json
在 ASTRA 中，图谱描述了扩展之间的数据流，协调它们的交互。例如，语音转文本（STT）扩展的文本输出可以指向大型语言模型（LLM）扩展。简而言之，图谱定义了涉及的扩展以及它们之间数据流的方向。开发者可以定制这种流程，将一个扩展（如 STT）的输出引导到另一个（如 LLM）。
# 拉取带有开发工具的 Docker 镜像，并将当前文件夹挂载为工作区
docker run -itd -v $(pwd):/app -w /app -p 8080:8080 --name astra_agents_dev ghcr.io/rte-design/astra_agents_build
在 ASTRA 中，有四种主要类型的扩展之间数据流：
# 对于 Windows Git Bash
# docker run -itd -v //$(pwd):/app -w //app -p 8080:8080 --name astra_agents_dev ghcr.io/rte-design/astra_agents_build
- Command
- Data
- Image frame
- PCM frame
# 进入 Docker 镜像
docker exec -it astra_agents_dev bash
通过在图谱中指定这些数据类型的方向，开发人员可以实现插件之间的相互调用和单向数据流。这对于 PCM 和图像数据类型尤其有用，简化了音频和视频处理。
# 构建 agent
make build
### ASTRA 代理应用
# 启动 agent
cd ./agents && ./bin/start
```

ASTRA 代理应用是一个可运行的服务器端应用程序，根据图谱规则结合多个扩展来完成更复杂的操作。
#### 2. 测试 voice agent

### ASTRA 云商店
前往 [Agora Web Demo](https://webdemo.agora.io/) 进行快速测试。

ASTRA 商店是一个集中的平台，开发人员可以在这里分享他们的扩展，并访问其他人创建的扩展。
请注意，`channel` 和 `remote_stream_id` 需要与您在 `https://webdemo.agora.io/` 上使用的一致。

### ASTRA 包管理器
输入相应的 RTC ID 和频道名称后，您应该能够看到日志并听到音频输出。

ASTRA 包管理器简化了上传、分享、下载和安装 ASTRA 扩展的过程。扩展可以指定对其他扩展和环境的依赖关系，ASTRA 包管理器会自动管理这些依赖关系，使扩展的安装和发布变得非常方便和直观。
<br>
<h2>ASTRA 服务</h2>

</br>
现在您已经创建了第一个 AI voice agent，创意并不会止步于此。 要开发更多的 AI agents， 您需要深入了解 ASTRA 的工作原理。请参阅 [ ASTRA 架构文档 ](./docs/astra-architecture.md)。

</br>
<br />
<h2>点星收藏</h2>

## 微信 ASTRA 中文群
我们更新频繁，不想错过的话，请给我们的 repo 点星，以便获得第一时间的更新.

<div align="center">
<img alt="ASTRA" width="300px" height="auto" src="../../images/wechat-qrcode.png">
</div>
![ASTRA star us gif](https://github.com/rte-design/ASTRA.ai/raw/main/images/star-the-repo-confetti-higher-quality.gif)


<br>
<h2>加入社区</h2>

- [Discord](https://discord.gg/VnPftUzAMJ)：非常适合分享您的应用程序并与社区互动。
- [WeChat Group](https://github.com/rte-design/ASTRA.ai/issues/125): 如果喜欢用微信群的社区，欢迎加入。
- [Github Discussion](https://github.com/rte-design/astra.ai/discussions)：非常适合提供反馈和提问。
- [GitHub Issues](https://github.com/rte-design/astra.ai/issues)：最适合报告错误和提出新功能。有关更多详细信息，请参阅我们的[贡献指南](./docs/code-of-conduct/contributing.md)。
- [X（以前的Twitter）](https://twitter.com/intent/follow?screen_name=AstraFramework)：非常适合分享您的代理并与社区互动。

<br>
<h2>代码贡献者</h2>

[![ASTRA](https://contrib.rocks/image?repo=rte-design/astra.ai)](https://github.com/rte-design/astra.ai/graphs/contributors)


</br>

## Contributing
<h2>欢迎贡献</h2>

欢迎贡献！请先阅读 [贡献指南](../code-of-conduct/contributing.md)。

</br>

## License
<h2>许可证授权</h2>

本项目使用 Apache 2.0 许可证授权 - 详细信息请参阅 [LICENSE](LICENSE)。

0 comments on commit b5acb09

Please sign in to comment.