feat: add and fix readme

telepace · Dec 30, 2024 · d5aa331 · d5aa331
1 parent 7c4b7f8
commit d5aa331
Showing 1 changed file with 114 additions and 125 deletions.
diff --git a/README.md b/README.md
@@ -23,51 +23,108 @@
     <a href="./README_zh-CN.md"><b>中文</b></a>
 </p>
 
+## 目录
 
-### 🧩 项目简介
+- [简介](#简介)
+- [快速开始](#快速开始)
+  - [安装](#安装)
+  - [配置](#配置)
+- [用法](#用法)
+- [架构图](#架构图)
+- [支持的操作](#支持的操作)
+- [实践指南](#实践指南)
+- [贡献](#贡献)
+- [许可证](#许可证)
+
+## 简介
 
 voiceflow 是一个基于 Go 语言的开源项目，旨在提供实时语音与大型语言模型（LLM）的交互能力。通过集成多种第三方语音平台和本地模型，voiceflow 支持实时语音转文本（STT）、文本转语音（TTS），以及与 LLM 的智能交互。
 
-核心功能：
+## 核心功能 🌟
 
-	•	实时语音转文本（STT）：支持集成多家云服务商的 STT 服务和本地模型，实时将用户语音转换为文本。
-	•	与 LLM 交互：将识别的文本直接发送给支持音频的 LLM，获取智能回复。
-	•	文本转语音（TTS）：将 LLM 的回复文本转换为语音，支持多种 TTS 服务和本地模型。
-	•	音频存储与访问：通过 MinIO 等存储服务，将生成的音频文件存储并提供访问路径，供前端实时播放。
-	•	可插拔的服务集成：采用模块化设计，支持各个 STT、TTS 服务和 LLM 的可插拔式集成，方便扩展和定制。
+- **实时语音转文本（STT）**：支持集成多家云服务商的 STT 服务和本地模型，实时将用户语音转换为文本。
+- **与 LLM 交互**：将识别的文本直接发送给支持音频的 LLM，获取智能回复。
+- **文本转语音（TTS）**：将 LLM 的回复文本转换为语音，支持多种 TTS 服务和本地模型。
+- **音频存储与访问**：通过 MinIO 等存储服务，将生成的音频文件存储并提供访问路径，供前端实时播放。
+- **可插拔的服务集成**：采用模块化设计，支持各个 STT、TTS 服务和 LLM 的可插拔式集成，方便扩展和定制。🎉
 
-### 🛫 快速开始
 
-	注意：以下指南将帮助您快速启动并运行 voiceflow。
 
-1. 克隆仓库
+## 快速开始
 
-git clone https://github.com/telepace/voiceflow.git
-cd voiceflow
+### 安装
 
-2. 配置环境
+1. **克隆仓库**
 
-	•	复制并修改 .env 文件，填写您的第三方服务 API 密钥和其他敏感信息。
+   ```bash
+   git clone https://github.com/telepace/voiceflow.git
+   cd voiceflow
+   ```
 
-cp configs/.env.example configs/.env
+2. **安装依赖**
 
-	•	修改 configs/config.yaml 文件，根据您的需求配置服务提供商和相关参数。
+   确保已安装 Go 1.16 或更高版本。
 
-3. 安装依赖
+   ```bash
+   go mod tidy
+   ```
 
-确保您已安装 Go 1.16 或更高版本。
+### 配置
 
-go mod tidy
+1. **复制示例环境变量文件**
 
-4. 运行应用
+   ```bash
+   cp configs/.env.example configs/.env
+   ```
 
-go run cmd/main.go
+   **编辑 `.env` 文件** 并填入相应的配置值：
+
+   ```env
+   # 环境变量示例
+   MINIO_ENDPOINT=play.min.io
+   MINIO_ACCESS_KEY=youraccesskey
+   MINIO_SECRET_KEY=yoursecretkey
+   AZURE_STT_KEY=yourazuresttkey
+   AZURE_TTS_KEY=yourazurettskey
+   ```
+
+2. **配置 `config.yaml`**
+
+   根据项目需求编辑 `configs/config.yaml`：
+
+   ```yaml
+   server:
+     port: 8080
+     enable_tls: false
+
+   minio:
+     enabled: true
+     bucket_name: voiceflow-audio
+
+   stt:
+     provider: azure  # 可选值：azure、google、local
+
+   tts:
+     provider: google  # 可选值：azure、google、local
+
+   llm:
+     provider: openai  # 可选值：openai、local
+
+   logging:
+     level: info
+   ```
 
-5. 前端连接
+### 启动应用
 
-前端可以通过 WebSocket 连接到 ws://localhost:8080/ws，开始实时语音交互。
+在项目根目录下运行：
 
-### 🕸️ 系统架构
+```bash
+go run cmd/main.go
+```
+
+查看服务是否正常启动，访问 `http://localhost:8080`。
+
+### 系统架构
 
 ```mermaid
 graph TD
@@ -80,14 +137,14 @@ graph TD
     B -- 音频URL --> A
 ```
 
-	•	前端浏览器：用户通过浏览器录制语音，并通过 WebSocket 发送到服务器。
-	•	WebSocket 服务器：接收前端的音频数据，协调各个服务模块的调用。
-	•	语音转文本（STT）：将音频数据转换为文本。
-	•	大型语言模型（LLM）：根据文本生成智能回复。
-	•	文本转语音（TTS）：将回复文本转换为语音数据。
-	•	存储服务（MinIO）：存储生成的音频文件，并提供访问 URL。
+- **前端浏览器**：用户通过浏览器录制语音，并通过 WebSocket 发送到服务器。
+- **WebSocket 服务器**：接收前端的音频数据，协调各个服务模块。
+- **语音转文本。(STT)**：将音频数据转换为文本。
+- **大型语言模型 (LLM)**：根据文本生成智能回复。
+- **文本转语音 (TTS)**：将回复文本转换为语音数据。
+- **存储服务 (MinIO)**：存储生成的音频文件，并提供访问 URL。
 
-### 🤖 目录结构
+### 目录结构
 
 ```bash
 voiceflow/
@@ -112,126 +169,58 @@ voiceflow/
 └── README.md              # 项目说明文档
 ```
 
+### 核心模块
 
-### 🔧 配置说明
-
-.env 文件
-
-用于存放敏感信息，如 API 密钥。
-
-```yaml
-# .env 示例
-MINIO_ENDPOINT=play.min.io
-MINIO_ACCESS_KEY=youraccesskey
-MINIO_SECRET_KEY=yoursecretkey
-AZURE_STT_KEY=yourazuresttkey
-AZURE_TTS_KEY=yourazurettskey
-```bash
-
-config.yaml 文件
-
-用于业务配置，如服务端口、启用的功能模块等。
-
-```yaml
-# config.yaml 示例
-server:
-  port: 8080
-  enable_tls: false
-
-minio:
-  enabled: true
-  bucket_name: voiceflow-audio
-
-stt:
-  provider: azure  # 可选值：azure、google、local
-
-tts:
-  provider: google  # 可选值：azure、google、local
-
-llm:
-  provider: openai  # 可选值：openai、local
-
-logging:
-  level: info
-```
-
-### 🛠️ 核心模块
-
-1. WebSocket 服务器
-
-使用 gorilla/websocket 实现，负责与前端的实时通信，接收音频数据并返回处理结果。
-
-2. 语音转文本（STT）
-
-	•	接口定义：internal/stt/stt.go 定义了 STT 服务的接口。
-	•	可插拔实现：支持 Azure、Google、本地模型等多种实现方式。
-
-3. 文本转语音（TTS）
-
-	•	接口定义：internal/tts/tts.go 定义了 TTS 服务的接口。
-	•	可插拔实现：支持 Azure、Google、本地模型等多种实现方式。
-
-4. 大型语言模型（LLM）
-
-	•	接口定义：internal/llm/llm.go 定义了与 LLM 交互的接口。
-	•	可插拔实现：支持 OpenAI、本地模型等多种实现方式。
-
-5. 存储模块
-
-	•	接口定义：internal/storage/storage.go 定义了存储服务的接口。
-	•	实现方式：默认使用 MinIO 进行音频文件的存储，也支持本地文件系统。
-
-
-### TODO
+1. **WebSocket 服务器**
 
-1. [ ] 消息总线
-2. [ ] 配置中心
-3. [ ] 容器化部署
-4. [ ] hooks
+   使用 `gorilla/websocket` 实现，负责与前端的实时通信，接收音频数据并返回处理结果。
 
+2. **语音转文本 (STT)**
 
-### 📖 使用指南
+   - **接口定义**：`internal/stt/stt.go` 定义了 STT 服务的接口。
+   - **可插拔实现**：支持 Azure、Google、本地模型等多种实现方式。
 
-集成新的 STT/TTS 服务
+3. **文本转语音 (TTS)**
 
-	1.	在对应的模块下新建文件夹，例如 internal/stt/yourservice。
-	2.	实现对应的接口，例如 Recognize 方法。
-	3.	在 NewService 方法中添加对新服务的支持。
+   - **接口定义**：`internal/tts/tts.go` 定义了 TTS 服务的接口。
+   - **可插拔实现**：支持 Azure、Google、本地模型等多种实现方式。
 
-配置 LLM 服务
+4. **大型语言模型 (LLM)**
 
-在 config.yaml 中修改 llm.provider，并在 internal/llm 下实现对应的 LLM 接口。
+   - **接口定义**：`internal/llm/llm.go` 定义了与 LLM 交互的接口。
+   - **可插拔实现**：支持 OpenAI、本地模型等多种实现方式。
 
-前端开发
+5. **存储模块**
 
-	•	WebSocket 通信：前端通过 WebSocket 与服务器通信，发送音频数据，接收处理结果。
-	•	音频播放：接收到服务器返回的音频 URL 后，使用 HTML5 Audio 播放。
+   - **接口定义**：`internal/storage/storage.go` 定义了存储服务的接口。
+   - **实现方式**：默认使用 MinIO 进行音频文件的存储，也支持本地文件系统。
 
 ### TODO
 
-+ 使用同一神经网络和模型处理语音：在此之前语音的实现是：一个简单模型将音频转录为文本，GPT-3.5 或 GPT-4 接收文本并输出文本，第三个简单模型将该文本转换回音频。相当于就是 `ASR -> LM -> TTS` 的这个过程。 这样做当然好， 但是也有一系列的缺陷，比如说延迟很高，比如说丢掉了细节，LLM 并不知道你的用户情感是什么。
-+ 允许对接和调用自己的 AI 中台。
+1. 消息总线
+2. 配置中心
+3. 容器化部署
+4. hooks
 
 ### 参考
 
-+ [https://openai.com/index/hello-gpt-4o/](https://openai.com/index/hello-gpt-4o/)
-+ [https://medium.com/@artificial--intelligence/the-differences-between-asr-and-tts-c85a08269c98](https://medium.com/@artificial--intelligence/the-differences-between-asr-and-tts-c85a08269c98#:~:text=We%20are%20familiar%20with%20the,analogous%20to%20the%20human%20mouth.)
+- [https://openai.com/index/hello-gpt-4o/](https://openai.com/index/hello-gpt-4o/)
+- [https://medium.com/@artificial--intelligence/the-differences-between-asr-and-tts-c85a08269c98](https://medium.com/@artificial--intelligence/the-differences-between-asr-and-tts-c85a08269c98#:~:text=We%20are%20familiar%20with%20the,analogous%20to%20the%20human%20mouth.)
 
-### 🤝 参与贡献
+### 参与贡献
 
 我们欢迎任何形式的贡献！请阅读 CONTRIBUTING.md 了解更多信息。
 
-	•	提交问题：如果您发现了 Bug，或者有新的功能建议，请在 Issues 中提交。
-	•	贡献代码：Fork 本仓库，在您的分支上进行修改，提交 Pull Request。
+- **提交问题**：如果您发现了 Bug，或者有新的功能建议，请在 Issues 中提交。
+- **贡献代码**：Fork 本仓库，在您的分支上进行修改，提交 Pull Request。
 
-### 📄 开源协议
+### 开源协议
 
 voiceflow 使用 [MIT](./LICENSE) 开源协议。
 
-### ❤️ 致谢
+### 致谢
 
 感谢所有为本项目做出贡献的开发者！
 
 <a href="https://github.com/telepace/voiceflow/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=telepace/voiceflow" />
-</a>