OFFICIAL_ALIGNMENT.md

官方配置对齐说明

📋 概述

本部署配置基于 High-Logic/Genie 官方仓库进行对齐，确保与上游项目保持一致性。

🔍 官方仓库分析

Docker 配置分析

从官方 Docker/Dockerfile 发现：

# Use official Python image
FROM python:3.12-slim

# Install system dependencies needed by PyAudio
RUN apt-get update && apt-get install -y \
    portaudio19-dev \
    python3-dev \
    build-essential \
 && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt

核心依赖

从官方源码分析得出的核心依赖：

• genie-tts: 官方包
• soundfile: 音频文件读写
• soxr: 高质量音频重采样
• onnxruntime: ONNX 模型推理
• huggingface_hub: 模型下载
• rich: 日志输出
• pyopenjtalk: 日语文本处理

API 使用方式

官方 API 调用方式：

import genie_tts as genie

# 1. 加载预定义角色
genie.load_predefined_character('misono_mika')

# 2. TTS 合成
genie.tts(
    character_name='misono_mika',
    text='どうしようかな……やっぱりやりたいかも……！',
    play=True,
    split_sentence=True,
    save_path="output.wav"
)

环境变量配置

官方推荐的环境变量：

# HuBERT 模型路径（可选）
os.environ['HUBERT_MODEL_PATH'] = r"C:\path\to\chinese-hubert-base.onnx"

# Open JTalk 字典路径（可选）
os.environ['OPEN_JTALK_DICT_DIR'] = r"C:\path\to\open_jtalk_dic_utf_8-1.11"

# 缓存配置（可选）
os.environ['Max_Cached_Character_Models'] = '3'
os.environ['Max_Cached_Reference_Audio'] = '10'

🔄 我们的对齐方案

1. 依赖配置对齐

更新前（问题）：

• 包含了非必需的 torch, torchaudio
• 缺少 soxr 高质量音频处理库
• 缺少官方核心包 genie-tts

更新后（对齐）：

# 核心TTS引擎 - 官方Genie包
genie-tts>=1.0.0

# 音频处理库（来自官方源码）
soundfile>=0.12.0
soxr>=0.3.0
scipy>=1.9.0
librosa>=0.10.0

# ONNX运行时（与官方对齐）
onnxruntime>=1.16.0

# 日语文本处理（官方要求）
pyopenjtalk

# 日志输出（与官方对齐）
rich>=12.0.0

2. API 调用对齐

更新前：

• 复杂的模型管理逻辑
• 自定义缓存处理

更新后：

# 直接使用官方API
genie.load_predefined_character(character_name)
genie.tts(
    character_name=character_name,
    text=processed_text,
    play=False,
    split_sentence=True,
    save_path=output_path
)

3. 环境变量对齐

# 基于官方文档设置环境变量
os.environ["HF_HUB_ENABLE_PROGRESS_BAR"] = "1"
os.environ["TOKENIZERS_PARALLELISM"] = "false"

# 可选的官方配置（注释形式）
# os.environ['HUBERT_MODEL_PATH'] = r"path/to/chinese-hubert-base.onnx"
# os.environ['OPEN_JTALK_DICT_DIR'] = r"path/to/open_jtalk_dic_utf_8-1.11"
# os.environ['Max_Cached_Character_Models'] = '3'
# os.environ['Max_Cached_Reference_Audio'] = '10'

🚀 PyAudio 问题解决

官方 Docker 处理方式

官方 Docker 通过系统级依赖解决：

RUN apt-get install -y portaudio19-dev python3-dev build-essential

Hugging Face Spaces 适配

由于 HF Spaces 限制，我们采用：

1. 移除 PyAudio：避免编译错误
2. Web 音频播放：通过 Gradio 界面播放
3. 备注说明：清楚标注处理方式

# Note: PyAudio is excluded for Hugging Face Spaces compatibility
# Audio playback is handled via web interface instead of local system audio

✅ 验证清单

• 使用官方 genie-tts 包
• 包含所有官方核心依赖（soundfile, soxr, onnxruntime）
• API 调用方式与官方一致
• 环境变量设置参考官方文档
• 错误处理机制完善
• 文档说明完整

🔗 参考资料

• Official GitHub Repository
• Official Documentation
• Docker Configuration
• API Tutorial
• Official Examples