# xszyou/fay architecture

> Architecture diagram of the GitHub repository xszyou/fay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xszyou/fay
- Repository: https://github.com/xszyou/fay

## Overview

下面针对FAY数字人框架（Fay）项目，说明如何绘制最准确、最清晰的系统设计架构图。按照模块区分与用户要求“线条更直、模块分区明确、使用中文”来展开。

##### 项目类型与目的
- 这是一个全栈数字人（虚拟人）应用框架，线下/线上均可部署，支持语音/文字交互、表情驱动、自动播报等功能。
- 上层可接入各种终端（网站、App、单片机），下层可自由替换ASR、TTS、LLM 和数字人模型。

##### 系统总体分区
按照功能层级大致可分为：
A. 接入层（前端 GUI / API）
B. 核心服务层（Core）
C. AI 能力层（ASR、TTS、LLM、AI 模块）
D. 辅助模块层（缓存、调度、仿真、持久化）
E. 外部依赖（第三方模型服务、数据库、消息通道等）

##### 主要组件与交互关系
- 用户交互
- Web/UI：gui/flask_server.py + gui/window.py
- 本地桌面：PyQt5 窗口 (main.py 启动)
- API 接口：REST/WebSocket
- 音频/文本处理
- recorder（core/recorder.py）负责录音
- socket_bridge_service（core/socket_bridge_service.py）负责音视频传输
- ASR 识别层
- asr/funasr、asr/ali_nls.py、asr/baidu_emotion.py 等
- 模式：本地离线和云端服务
- 语义与对话管理（Core）
- fay_core（核心逻辑）、interact、stream_manager（流式管理）、authorize_tb（权限）、member_db/content_db（上下文存储）、qa_service（问答）、wsa_server（WebSocket API）
- LLM 与智能代理
- llm/ 下多种大语言模型封装（ChatGLM3、GPT、Rasa、Ollama API 等）
- Agent 服务：llm/agent/*.py + genagents/genagents_flask.py
- TTS 合成层
- tts/ali_tss.py、gptsovits、ms_tts_sdk、volcano 等
- 调度与仿真
- scheduler/thread_manager.py（多线程管理）
- simulation_engine/（内置仿真工具、Prompt 模板）
- 辅助与工具
- utils/（配置、OpenAI API 代理、流式工具等）
- cache_data/（音频临时缓存）
- 持久化
- 系统配置：system.conf
- 数据文件：config.json、qa.csv、verifier.json

##### 架构模式与设计原则
- 分层解耦：前端、核心、AI 能力、调度/仿真、工具各司其职
- 插件化与策略模式：不同 ASR/TTS/LLM 模块可按需替换
- 流式处理：全链路支持流式输入输出
- 多路并发与多用户支持：通过多线程/异步与 WebSocket 管道实现

##### 绘图建议（满足“线条更直、模块间区分开”要求）
- 使用矩形区域将五大层区分开，用不同背景色或轮廓色标识
- 组件内部用子矩形（子模块）细分，并标注其文件/包名
- 用水平和垂直的直线箭头展示调用或数据流：
- 录音 → ASR → 语义引擎 → Agent/LLM → TTS → 播放
- 前端请求 → Core API → 数据库/缓存
- Agent → 外部 API（OpenAI、Rasa）
- 箭头上方标注 Protocol（HTTP、WebSocket、gRPC 等）和格式（JSON、音频流）
- 配色示例
- 接入层：浅蓝色
- 核心层：浅绿色
- AI 能力：浅橙色
- 调度/仿真：浅紫色
- 辅助工具：灰色

##### 针对Fay项目的细节要点
- 在“核心服务层”矩形中，列出 fay_core、interact、stream_manager、socket_bridge_service 等
- 在“AI 能力层”分四个子区：ASR、LLM、Agent、TTS
- “调度与仿真”区单独放 simulation_engine 和 scheduler
- “辅助工具”区放 utils、cache_data
- “外部依赖”区：数据库（member_db、content_db），第三方接口（OpenAI、百度、阿里等）
- 确保各层之间箭头方向单一且直：自上而下或自左而右

##### 绘制要点总结
- 模块矩形：清晰标注名称、文件路径
- 箭头：使用直线连接，避免交叉，箭头头部清晰
- 色块分区：不同层次用不同颜色或边框
- 文字：全部中文，字体统一，尺寸区分主次
- 图例：在图的一侧加上色块/箭头样式说明

通过以上分层、配色、子模块标注和直线箭头的方式，即可绘制出符合Fay数字人框架的详尽且结构清晰的系统设计图。务必将各功能区隔离开，线条直且不交叉，中文注释完整，保证图形化展现与源码一一对应。

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% 接入层
    subgraph "接入层" 
        direction TB
        GUI1["Web/UI 前端\n(gui/flask_server.py)"]:::accessLayer
        GUI2["窗口界面\n(gui/window.py)"]:::accessLayer
        Desktop["本地桌面启动\n(main.py)"]:::accessLayer
        API["API 接口服务\n(core/wsa_server.py)"]:::accessLayer
    end

    %% 核心服务层
    subgraph "核心服务层"
        direction TB
        Recorder["录音模块\n(core/recorder.py)"]:::coreLayer
        SocketBridge["音视频传输桥接\n(core/socket_bridge_service.py)"]:::coreLayer
        FayCore["核心逻辑\n(core/fay_core.py)"]:::coreLayer
        Interact["交互流程\n(core/interact.py)"]:::coreLayer
        StreamManager["流式管理\n(core/stream_manager.py)"]:::coreLayer
        Authorize["权限控制\n(core/authorize_tb.py)"]:::coreLayer
        MemberDB["用户上下文存储\n(core/member_db.py)"]:::coreLayer
        ContentDB["上下文存储\n(core/content_db.py)"]:::coreLayer
        QAService["问答服务\n(core/qa_service.py)"]:::coreLayer
    end

    %% AI 能力层
    subgraph "AI 能力层"
        direction TB
        subgraph "ASR 识别层"
            direction TB
            ASR_LocalCloud["本地/云端 ASR\n(asr/funasr/, asr/ali_nls.py)"]:::aiLayer
            ASR_Emotion1["情感识别\n(ai_module/baidu_emotion.py)"]:::aiLayer
            ASR_Emotion2["情感识别\n(ai_module/nlp_cemotion.py)"]:::aiLayer
        end
        subgraph "LLM 能力层"
            direction TB
            LLMModels["多模型封装\n(llm/nlp_*.py)"]:::aiLayer
        end
        subgraph "智能代理 Agent"
            direction TB
            AgentService["Agent 服务\n(llm/agent/agent_service.py, fay_agent.py)"]:::aiLayer
            GenAgentsAPI["GenAgents API\n(genagents/genagents_flask.py)"]:::aiLayer
        end
        subgraph "TTS 合成层"
            direction TB
            TTS1["TTS Ali\n(tts/ali_tss.py)"]:::aiLayer
            TTS2["GPTSovits\n(tts/gptsovits.py)"]:::aiLayer
            TTS3["MS TTS SDK\n(tts/ms_tts_sdk.py)"]:::aiLayer
            TTS4["TTS Voice\n(tts/tts_voice.py)"]:::aiLayer
            TTS5["Volcano TTS\n(tts/volcano_tts.py)"]:::aiLayer
        end
    end

    %% 调度与仿真层
    subgraph "调度与仿真层"
        direction TB
        Scheduler["多线程调度\n(scheduler/thread_manager.py)"]:::schedLayer
        SimulationEngine["仿真引擎\n(simulation_engine/)"]:::schedLayer
    end

    %% 辅助模块层
    subgraph "辅助模块层"
        direction TB
        CacheData["缓存数据\n(cache_data/)"]:::utilLayer
        Utils["工具函数与 API 代理\n(utils/)"]:::utilLayer
    end

    %% 外部依赖
    subgraph "外部依赖"
        direction TB
        ExternalDB["数据库\n(member_db, content_db)"]:::extLayer
        ThirdParty["第三方接口\n(OpenAI, 百度, 阿里)"]:::extLayer
    end

    %% 连接线
    GUI1 -->|"HTTP/WebSocket"| API
    GUI2 -->|启动| Desktop
    Desktop -->|调用| Recorder
    API -->|"WebSocket"| FayCore
    Recorder -->|"音频流"| ASR_LocalCloud
    Recorder -->|"情感数据"| ASR_Emotion1
    Recorder -->|"情感数据"| ASR_Emotion2
    ASR_LocalCloud -->|"文本| JSON"| FayCore
    ASR_Emotion1 -->|"JSON"| FayCore
    ASR_Emotion2 -->|"JSON"| FayCore
    FayCore -->|"调用"| Interact
    Interact -->|"流式数据"| StreamManager
    StreamManager -->|"授权"| Authorize
    Authorize -->|"查询"| MemberDB
    Authorize -->|"查询"| ContentDB
    Interact -->|"问答请求"| QAService
    QAService -->|"上下文"| ContentDB
    Interact -->|"调用"| AgentService
    AgentService -->|"HTTP"| LLMModels
    AgentService -->|"HTTP"| GenAgentsAPI
    AgentService -->|"调用"| ThirdParty
    FayCore -->|"合成请求"| TTS1
    FayCore -->|"合成请求"| TTS2
    FayCore -->|"合成请求"| TTS3
    FayCore -->|"合成请求"| TTS4
    FayCore -->|"合成请求"| TTS5
    StreamManager -->|"调度任务"| Scheduler
    SimulationEngine -->|"模型仿真"| AgentService
    Utils -->|"支持"| ASR_LocalCloud
    Utils -->|"支持"| TTS1
    FayCore -->|"持久化"| CacheData
    FayCore -->|"配置读取"| Utils
    FayCore -->|"持久化"| ExternalDB

    %% 点击事件
    click GUI1 "https://github.com/xszyou/fay/blob/main/gui/flask_server.py"
    click GUI2 "https://github.com/xszyou/fay/blob/main/gui/window.py"
    click Desktop "https://github.com/xszyou/fay/blob/main/main.py"
    click API "https://github.com/xszyou/fay/blob/main/core/wsa_server.py"
    click Recorder "https://github.com/xszyou/fay/blob/main/core/recorder.py"
    click SocketBridge "https://github.com/xszyou/fay/blob/main/core/socket_bridge_service.py"
    click ASR_LocalCloud "https://github.com/xszyou/fay/tree/main/asr/funasr/"
    click ASR_LocalCloud "https://github.com/xszyou/fay/blob/main/asr/ali_nls.py"
    click ASR_Emotion1 "https://github.com/xszyou/fay/blob/main/ai_module/baidu_emotion.py"
    click ASR_Emotion2 "https://github.com/xszyou/fay/blob/main/ai_module/nlp_cemotion.py"
    click FayCore "https://github.com/xszyou/fay/blob/main/core/fay_core.py"
    click Interact "https://github.com/xszyou/fay/blob/main/core/interact.py"
    click StreamManager "https://github.com/xszyou/fay/blob/main/core/stream_manager.py"
    click Authorize "https://github.com/xszyou/fay/blob/main/core/authorize_tb.py"
    click MemberDB "https://github.com/xszyou/fay/blob/main/core/member_db.py"
    click ContentDB "https://github.com/xszyou/fay/blob/main/core/content_db.py"
    click QAService "https://github.com/xszyou/fay/blob/main/core/qa_service.py"
    click LLMModels "https://github.com/xszyou/fay/blob/main/llm/nlp_ChatGLM3.py"
    click LLMModels "https://github.com/xszyou/fay/blob/main/llm/nlp_gpt.py"
    click LLMModels "https://github.com/xszyou/fay/blob/main/llm/nlp_ollama_api.py"
    click AgentService "https://github.com/xszyou/fay/blob/main/llm/agent/agent_service.py"
    click AgentService "https://github.com/xszyou/fay/blob/main/llm/agent/fay_agent.py"
    click GenAgentsAPI "https://github.com/xszyou/fay/blob/main/genagents/genagents_flask.py"
    click TTS1 "https://github.com/xszyou/fay/blob/main/tts/ali_tss.py"
    click TTS2 "https://github.com/xszyou/fay/blob/main/tts/gptsovits.py"
    click TTS3 "https://github.com/xszyou/fay/blob/main/tts/ms_tts_sdk.py"
    click TTS4 "https://github.com/xszyou/fay/blob/main/tts/tts_voice.py"
    click TTS5 "https://github.com/xszyou/fay/blob/main/tts/volcano_tts.py"
    click Scheduler "https://github.com/xszyou/fay/blob/main/scheduler/thread_manager.py"
    click SimulationEngine "https://github.com/xszyou/fay/tree/main/simulation_engine/"
    click CacheData "https://github.com/xszyou/fay/tree/main/cache_data/"
    click Utils "https://github.com/xszyou/fay/tree/main/utils/"
    click ExternalDB "https://github.com/xszyou/fay/tree/main/member_db"
    click ExternalDB "https://github.com/xszyou/fay/tree/main/content_db"

    %% 样式定义
    classDef accessLayer fill:#D0E8FF,stroke:#4AA3DF;
    classDef coreLayer fill:#D0F0D0,stroke:#4CAF50;
    classDef aiLayer fill:#FFE6B8,stroke:#FF9800;
    classDef schedLayer fill:#E8D0FF,stroke:#9C27B0;
    classDef utilLayer fill:#F0F0F0,stroke:#9E9E9E;
    classDef extLayer fill:#FFD0D0,stroke:#F44336;
```
