freya v2

Freya v2.0

具有持久记忆和MCP集成的位置感知多房间个人AI助理

](https://github.com/MrPink1977/freya_v2)  

______________________________________________________________________

🎯 Freya是什么？

Freya是为现代家庭设计的下一代个人人工智能助理。她机智、聪明、真正乐于助人——能够在多个房间里进行自然对话，记住你的喜好，并代表你采取行动。

与危害您隐私的依赖云的助手不同，Freya主要在您自己的硬件上运行，让您完全控制数据，同时提供卓越的个性化体验。

✨ 主要特点

• 🏠 多房间音响：卧室和前门端点，易于扩展
• 📍 位置识别：知道你在哪里，并做出相应的回应
• 🧠 智能存储器：持久记忆系统，随着时间的推移学习你的偏好
• 🔧 400+工具：通过模型上下文协议（MCP）可扩展的工具生态系统
• 👁️ 视觉能力：前门的运动和物体检测
• 🎭 适应性人格：机智、讽刺、有语境意识
• 🖥️ 实时仪表板：用于监视和控制WebSocket安全的全面web GUI
• 🔒 隐私第一：核心处理在您的硬件上本地运行
• 🎤 语音交互：具有语音转文本和文本转语音功能的完整音频管道
• 🔊 音频管理器：基于PyAudio的麦克风和扬声器管理
• ✅ 已测试：43个以上的单元和集成测试，代码覆盖率为70%
• 🔐 安全：WebSocket连接的JWT身份验证、速率限制和会话管理

🏗️ 建筑

Freya建立在面向服务的架构之上，具有连接独立微服务的Redis消息总线：

Architecture Diagram

核心组件

• 音频管理器：具有位置感知的多端点音频路由
• LLM发动机：RTX 5060 Ti上的局部模型推理（Llama 3.2）
• 内存管理器：带ChromaDB矢量存储的自适应内存v3
• MCP网关：通过MetaMCP/MCPX集成通用工具
• 视觉服务：OpenCV+YOLO用于实时目标检测
• Web仪表板：带有FastAPI后端的React/Svelte前端

📚 文档

此存储库包含Freya v2.0的完整设计规范：

• 执行摘要 -高瞻远瞩和关键差异化因素
• 需求 -详细的功能和技术要求
• 建筑 -系统设计和组件分解
• 路线图 -12周实施计划和技术栈

🚀 快速开始

先决条件

• Python 3.11+
• Docker&Docker编写
• NVIDIA GPU（RTX 5060 Ti或类似型号）
• CUDA 12.0+
• 系统音频依赖关系（portaudio、ffmpeg）

安装

# Clone the repository
git clone https://github.com/MrPink1977/freya_v2.git
cd freya_v2

# Install system dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y portaudio19-dev ffmpeg libsndfile1

# For macOS
# brew install portaudio ffmpeg libsndfile

# Install Python dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start backend services
docker-compose up -d redis ollama chromadb

# Start Freya Core
python -m src.main

ElevenLabs TTS设置（可选但推荐）

要获得高质量的文本到语音转换，请设置ElevenLabs：

1. 从获取API密钥 十一实验室
2. 添加到 .env:

   ELEVENLABS_API_KEY="your_api_key_here"
   ELEVENLABS_VOICE_ID="21m00Tcm4TlvDq8ikWAM"  # Rachel (default)

看 docs/ELEVENLABS_SETUP.md 有关详细的设置说明。

⚙️ 配置

Freya使用环境变量进行配置。关键设置：

核心设置

# Redis (Message Bus)
REDIS_HOST=localhost
REDIS_PORT=6379

# Ollama (Local LLM)
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=llama3.2:3b

# ChromaDB (Vector Database)
CHROMADB_HOST=localhost
CHROMADB_PORT=8000

音频配置

# Audio Manager
AUDIO_SAMPLE_RATE=16000
AUDIO_CHANNELS=1
AUDIO_CHUNK_SIZE=1024
AUDIO_INPUT_DEVICE_INDEX=-1  # -1 for default
AUDIO_OUTPUT_DEVICE_INDEX=-1  # -1 for default

# STT (Speech-to-Text)
STT_MODEL=base
STT_LANGUAGE=en
STT_DEVICE=cuda  # or cpu

# TTS (Text-to-Speech)
TTS_PROVIDER=elevenlabs  # elevenlabs or local
ELEVENLABS_API_KEY=your_key_here
ELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM
ELEVENLABS_MODEL=eleven_monolingual_v1
ELEVENLABS_STABILITY=0.5
ELEVENLABS_SIMILARITY_BOOST=0.75

GUI安全配置

# JWT Authentication
GUI_JWT_SECRET=change-this-secret-in-production
GUI_TOKEN_EXPIRY=3600  # 1 hour in seconds
GUI_SESSION_TIMEOUT=3600  # 1 hour in seconds
GUI_MAX_SESSIONS=100  # Maximum concurrent WebSocket sessions

# Rate Limiting
GUI_RATE_LIMIT_RATE=10.0  # Requests per second per session
GUI_RATE_LIMIT_BURST=20  # Burst size

看 src/core/config.py 对于所有可用的配置选项。

🧪 测试

Freya具有全面的测试覆盖范围，包括单元和集成测试。

运行测试

# Run all tests with coverage
pytest tests/ -v --cov=src --cov-report=term-missing --cov-report=html

# Run only unit tests
pytest tests/unit/ -v

# Run only integration tests
pytest tests/integration/ -v

# Run specific test file
pytest tests/unit/test_tts_service.py -v

# Run tests with specific markers
pytest -m unit -v
pytest -m integration -v
pytest -m slow -v

测试覆盖率

• 总体：新代码覆盖率约为70%
• 核心模块：85%以上的覆盖率（message_bus、config、base_service）
• 服务模块：70%以上的覆盖率（tts、audio_manager、gui）
• 43+次测试 跨单元和集成套件
• CI/CD：通过GitHub Actions对每个提交进行自动测试

看 测试.md 获取全面的测试文档。

🔒 安全

WebSocket身份验证

GUI仪表板使用基于JWT的身份验证：

1. 获取令牌: POST /api/auth/token 包含客户信息
2. 连接WebSocket: ws://localhost:8000/ws?token={jwt_token}
3. 刷新令牌: POST /api/auth/refresh 使用当前令牌

速率限制

• 每IP限制：防止连接滥用
• 每次会话限制：控制每个WebSocket连接的消息速率
• 滑动窗口算法：公平准确的利率限制

会话管理

• 过期会话的自动会话清理
• 最大并发会话限制
• 活动跟踪和超时执行

📖 用法

开始Freya

# Start backend services
docker-compose up -d

# Start Freya Core (includes all services)
python -m src.main

# Access GUI Dashboard
# Open http://localhost:8000 in browser

使用音频管道

# Publish text for TTS
await message_bus.publish("tts.generate", {
    "text": "Hello, how can I help you?",
    "timestamp": datetime.now().isoformat()
})

# Subscribe to audio output
async def handle_audio(data):
    audio_bytes = data.get("audio")
    # Play audio or save to file
    
await message_bus.subscribe("audio.output.stream", handle_audio)

正在运行MCP服务器

# Install MCP servers
bash scripts/install_mcp_servers.sh

# MCP servers are automatically started by Freya
# Check logs for: "✓ Connected to MCP server: "

🗓️ 发展路线图

请参阅 完整路线图 查看详细的任务分解。

🛠️ 技术栈

🤝 贡献

这是一个个人项目，但欢迎提供意见、建议和反馈！请打开一个问题来讨论重大更改。

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 自适应内存v3 -OpenWebUI社区的内存系统
• 模型上下文协议 -Anthropic工具集成标准
• 很棒的mcp服务器 -400+预构建MCP服务器

📞 联系

• github： @平克先生1977
• 项目： 弗雷亚v2

______________________________________________________________________

状态: ✅ 第2阶段后端完成（v0.4.0）-音频管道完全实现！\ 下一步：阶段2D-前端GUI增强（调试面板、音频测试仪）