头像渲染器MCP
    ](https://github.com/astral-sh/uv)
具有企业级MCP集成的生产就绪人工智能语音头生成系统
______________________________________________________________________
一个高性能、可扩展的化身渲染引擎，使用最先进的深度学习模型将静态图像和音频转换为逼真的说话头视频。
______________________________________________________________________
关于
Avatar渲染器MCP是一个为生产环境设计的复杂视频生成系统。它结合了多种尖端的人工智能模型（FOMM、Diff2Lip、Wav2Lip、SadTalker），只需两个输入即可创建逼真的说话化身：
- 🖼️ 静止图像 一个人的脸
- 🎤 音频文件 包含言语
人工智能分析这两个输入，并生成一个视频，在视频中，这个人似乎在自然地说话，嘴唇动作、面部表情和头部姿势动画同步。
关键差异
- 生产就绪架构：为企业部署而构建，支持Kubernetes、Docker和自动扩展
- MCP协议集成：原生模型上下文协议（MCP）支持无缝AI代理通信
- 智能回退系统：自动GPU内存管理，具有优雅的降级功能
- 可扩展设计：基于Celery的分布式任务处理，具有KEDA自动扩展功能
- 云原生：包括Helm图表、Kubernetes清单和Terraform配置
______________________________________________________________________
特性
核心能力
- ✅ 双质量模式：实时流媒体模式+高质量内容创作模式
- ✅ 实时绘制：直播新闻和聊天机器人的延迟\200 FPS
- ✅ MCP STDIO服务器：已准备好与自动发现的AI代理集成
- ✅ RESTful API：基于FastAPI的HTTP接口，具有全面的健康检查功能
- ✅ 面部增强：内置GFPGAN支持，可提高输出质量
- ✅ 安装验证：自动检查依赖关系和配置
DevOps和基础设施
- ✅ 容器化：支持CUDA 12.4的生产级Dockerfile
- ✅ Kubernetes就绪：K8s部署的Helm图表和原始清单
- ✅ 自动缩放：KEDA集成用于基于需求的吊舱扩展
- ✅ CI/CD管道：使用GitHub Actions工作流进行自动化测试
- ✅ 健康检查：全面
/avatars模型状态的端点 - ✅ 安装验证：自动依赖关系和配置验证
- ✅ 监控：Prometheus指标和结构化日志
- ✅ 云存储：S3/COS集成用于输出交付
______________________________________________________________________
安装
先决条件
- python：3.11或3.12
- 图形处理器：配备CUDA 12.4+的NVIDIA GPU（可选，但推荐）
- 包管理器: 紫外线 （推荐）或pip
- FFmpeg：支持GPU加速编码的NVENC
- 码头工人：（可选）用于集装箱化部署
快速开始
1.安装uv（推荐的软件包管理器）
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or via pip
pip install uv2.克隆存储库
git clone https://github.com/ruslanmv/avatar-renderer-mcp.git
cd avatar-renderer-mcp3.安装依赖项
# Install production dependencies
make install
# OR install with development tools
make dev-install4.验证安装
# Run comprehensive installation verification
python scripts/verify_installation.py这将检查：
- ✅ Python版本兼容性
- ✅ 所有依赖项均已正确安装
- ✅ 模块导入工作
- ✅ 已配置API终结点
- ✅ 可用的质量模式
- ✅ GPU可用性（可选）
5.下载模型检查点
# Downloads ~3GB of model weights
make download-models6.运行服务器
# Start FastAPI REST server on http://localhost:8080
make run
# OR start MCP STDIO server
make run-stdio手动安装（无品牌）
# Create virtual environment with uv
uv venv .venv --python 3.11
# Activate virtual environment
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
# Install dependencies
uv pip install -e ".[dev]"
# Run the application
uvicorn app.api:app --host 0.0.0.0 --port 8080 --reload______________________________________________________________________
用法
REST API示例
# Submit a rendering job
curl -X POST http://localhost:8080/render \
-H 'Content-Type: application/json' \
-d '{
"avatarPath": "/path/to/avatar.png",
"audioPath": "/path/to/speech.wav"
}'
# Response
{
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"statusUrl": "/status/550e8400-e29b-41d4-a716-446655440000",
"async": true
}
# Check job status or download result
curl http://localhost:8080/status/550e8400-e29b-41d4-a716-446655440000MCP集成
向您的MCP网关注册：
curl -X POST http://gateway:4444/servers \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "avatar-renderer",
"transport": "stdio",
"command": "/usr/bin/python3",
"args": ["/app/mcp_server.py"],
"autoDiscover": true
}'网关将自动发现 render_avatar 工具via mcp-tool.json.
Python API示例
from app.pipeline import render_pipeline
# Real-time mode for live streaming
render_pipeline(
face_image="avatars/person.jpg",
audio="audio/speech.wav",
out_path="output/result.mp4",
quality_mode="real_time" # Fast processing for streaming
)
# High-quality mode for YouTube content
render_pipeline(
face_image="avatars/person.jpg",
audio="audio/speech.wav",
out_path="output/result.mp4",
quality_mode="high_quality" # Best quality with GFPGAN
)______________________________________________________________________
质量模式
Avatar渲染器MCP支持 两种不同的质量模式 针对不同的用例进行了优化：
🚀 实时模式
非常适合直播、新闻广播和交互式聊天机器人
- 速度：\ B{FastAPI Gateway}
B --> C[Celery Worker Queue] C --> D[GPU Node] D --> E[FOMM Head Pose] E --> F{GPU Memory Check} F -->|Sufficient| G[Diff2Lip Diffusion] F -->|Constrained| H[SadTalker + Wav2Lip] G --> I[GFPGAN Enhancement] H --> I I --> J[FFmpeg NVENC Encoding] J --> K[Cloud Storage Upload] K --> L[Return Signed URL]
### 组件概述
|组件|用途|技术|
|-----------|---------|------------|
| **快速API** |REST API网关| Python、uvicorn|
| **MCP服务器** |STDIO协议处理程序| Python，异步|
| **芹菜** |分布式任务队列|Redis、RabbitMQ|
| **FOMM** |头部姿势生成| PyTorch，CUDA|
| **Diff2Lip** |基于扩散的唇同步|稳定扩散|
| **悲伤者** |回退运动模型|3DMM，PyTorch|
| **Wav2Lip** |回退唇形同步GAN|PyTorch|
| **GFPGAN** |面部增强| GAN、PyTorch|
| **FFmpeg** |视频编码|H.264 NVENC|
______________________________________________________________________
## 配置
所有配置均通过环境变量或 `.env` 文件：
General Settings
LOG_LEVEL=INFO TMP_DIR=/tmp
GPU Configuration
CUDA_VISIBLE_DEVICES=0 TORCH_USE_INT8=false
Celery (Optional - leave empty for local mode)
CELERY_BROKER_URL=redis://localhost:6379/0 CELERY_BACKEND_URL=redis://localhost:6379/0 CELERY_CONCURRENCY=1
Model Paths
MODEL_ROOT=/models FOMM_CKPT_DIR=/models/fomm DIFF2LIP_CKPT_DIR=/models/diff2lip SADTALKER_CKPT_DIR=/models/sadtalker WAV2LIP_CKPT=/models/wav2lip/wav2lip_gan.pth GFPGAN_CKPT=/models/gfpgan/GFPGANv1.4.pth
FFmpeg
FFMPEG_BIN=ffmpeg
MCP Integration
MCP_ENABLE=true MCP_TOOL_NAME=avatar_renderer
______________________________________________________________________
## 发展
### 设置开发环境
Install all dependencies including dev tools
make dev-install
Install pre-commit hooks
make pre-commit-install
### 代码质量
Run linters (ruff, mypy, black)
make lint
Auto-format code
make format
Run tests with coverage
make test
Run all checks
make check
### 测试
Run all tests
make test
Run specific test categories
make test-unit # Unit tests only make test-integration # Integration tests only make test-gpu # GPU-dependent tests
______________________________________________________________________
## 部署
### 码头工人
Build Docker image
make docker-build
Run with GPU support
make docker-run
Or manually
docker build -t avatar-renderer:latest . docker run --gpus all -p 8080:8080 \ -v $(pwd)/models:/models:ro \ avatar-renderer:latest
### Kubernetes/Helm
Deploy using Helm
helm upgrade --install avatar-renderer ./charts/avatar-renderer \ --namespace videogenie \ --create-namespace \ --set image.tag=$(git rev-parse --short HEAD) \ --set resources.limits.nvidia\\.com/gpu=1
Or use raw manifests
kubectl apply -f k8s/
### KEDA自动缩放
部署包括KEDA `ScaledObject` 基于以下因素扩展Pod的配置：
- Kafka消息延迟
- Redis队列深度
- 自定义Prometheus指标
______________________________________________________________________
## 演出
|度量|值|硬件|
|--------|-------|----------|
| **FPS（编码）** |>200 fps | V100 GPU|
| **延迟（512x512）** |~2.5秒| V100，NVENC|
| **VRAM使用情况** |6-12GB |取决于管道|
| **CPU 核心** |2-4推荐|用于预处理|
| **吞吐量** |100+个工作岗位/小时|单台V100|
______________________________________________________________________
## 项目结构
avatar-renderer-mcp/ ├── app/ # Application source code │ ├── __init__.py # Package initialization │ ├── api.py # FastAPI REST endpoints │ ├── mcp_server.py # MCP STDIO protocol server │ ├── pipeline.py # Core rendering pipeline │ ├── settings.py # Configuration management │ ├── viseme_align.py # Phoneme-to-viseme alignment │ └── worker.py # Celery task worker ├── tests/ # Test suite │ ├── __init__.py │ ├── conftest.py │ ├── test_api.py │ └── test_mcp_stdio.py ├── scripts/ # Utility scripts │ ├── benchmark.py │ └── download_models.sh ├── charts/ # Helm deployment charts ├── k8s/ # Raw Kubernetes manifests ├── terraform/ # Infrastructure as Code ├── docs/ # Documentation ├── .gitignore # Git ignore rules ├── Dockerfile # Container definition ├── LICENSE # Apache 2.0 license ├── Makefile # Build automation ├── pyproject.toml # Project metadata & dependencies └── README.md # This file
______________________________________________________________________
## 故障排除
### 常见问题
|问题|解决方案|
|---------|----------|
| `CUDA out of memory` |减少Diff2Lip步数或使用Wav2Lip回退|
| `Green/black artifacts` |更新NVIDIA驱动程序（≥545），检查FFmpeg NVENC支持|
| `Lips drift from audio` |检查音素对齐，将音频重新采样到16kHz|
| `Models not found` |快跑 `make download-models` |
| `uv not found` |安装紫外线： `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
### 调试模式
Enable debug logging
export LOG_LEVEL=DEBUG
Run with verbose output
make run
______________________________________________________________________
## 路线图
- \[\]实时渲染的WebRTC流媒体支持
- \[\]低延迟应用的增量合成
- \[\]多语言音素支持
- \[\]高级情绪控制
- \[\]云原生TTS集成
- \[\]多GPU分布式渲染
______________________________________________________________________
## 贡献
欢迎投稿！请遵循以下指南：
1. 复刻仓库
1. 创建要素分支(`git checkout -b feature/amazing-feature`)
1. 提交您的更改(`git commit -m 'Add amazing feature'`)
1. 推到分支(`git push origin feature/amazing-feature`)
1. 打开拉取请求
确保所有测试通过，代码符合PEP 8标准：
make check
______________________________________________________________________
## 许可证
该项目根据 **Apache许可证2.0** -看看 [许可证](LICENSE) 文件以获取详细信息。
Copyright 2025 Ruslan Magana Vsevolodovna
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
______________________________________________________________________
## 作者
**鲁斯兰·马加纳·维谢沃洛多夫娜**
- 🌐 网站： [ruslanmv.com](https://ruslanmv.com)
- 📧 电子邮件：contact@ruslanmv.com
- 💼 github： [@ruslanmv](https://github.com/ruslanmv)
______________________________________________________________________
## 致谢
该项目建立在几个研究团队的工作之上：
- **FOMM** （一阶运动模型）- [Aliaksandr Siarohin等人，神经IPS 2020](https://github.com/AliaksandrSiarohin/first-order-model)
- **Diff2Lip** -基于扩散的唇同步研究
- **悲伤者** - [张等，CVPR 2023](https://github.com/OpenTalker/SadTalker)
- **Wav2Lip** - [K R Prajwal等人，ACM MM 2020](https://github.com/Rudrabha/Wav2Lip)
- **GFPGAN** - [腾讯ARC实验室，2021](https://github.com/TencentARC/GFPGAN)
特别感谢开源人工智能社区在生成模型方面的最新进展。
______________________________________________________________________
## 支持
有关问题、疑问或功能请求，请：
1. 检查 [故障排除](#troubleshooting) 章节
1. 搜索 [现有问题](https://github.com/ruslanmv/avatar-renderer-mcp/issues)
1. 打开A [新发行的](https://github.com/ruslanmv/avatar-renderer-mcp/issues/new) 详细信息
如需商业支持或咨询，请联系： **contact@ruslanmv.com**
______________________________________________________________________
Made with ❤️ by Ruslan Magana Vsevolodovna
Transforming still images into lifelike talking avatars