数字人平台 Python 后端

对应 Java 侧 yudao-module-digital 通过 HTTP 调用的 AI 能力接口。

目录

app.py                 # FastAPI 主应用，所有 HTTP 接口
config.py              # 配置（环境变量可覆盖）
requirements.txt
services/
  llm.py               # LLM 封装（OpenAI 兼容，用于文案/PPT 生成）
  minio_util.py        # MinIO 上传/下载
  voice.py             # 语音：ASR、TTS、声音训练预处理
  video.py             # 视频：ffmpeg 合成/分辨率/字幕/首帧/抠图/图层合成
  wav2lip.py           # 口型合成（Wav2Lip，CPU 可跑）
  musetalk.py          # 口型合成（MuseTalk，远程 HTTP，需 GPU）
  ppt.py               # PPT 生成（LLM + python-pptx + Pillow）
  ppt_master.py        # ppt-master 引擎封装（Anthropic tool-use 驱动）
  image_search.py      # 百度图片搜索（关键词抓图，带缓存）
  templates/           # PPT 模板（mode1/mode2/themes.json）
scripts/
  download_backgrounds.py  # 批量下载背景图并上传 MinIO、输出入库 SQL
skills/
  ppt-master/          # vendor 的 ppt-master 引擎（/generate_ppt_master 用）
docs/                  # 设计文档（api-service-design / ppt-spec / deck-template-authoring）

启动

cd digital-human-engine
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
.venv/bin/uvicorn app:app --host 0.0.0.0 --port 60013

依赖说明：requirements.txt 仅覆盖 HTTP/语音链路。抠图、视频、PPT 功能还依赖 numpy、av、opencv-python、Pillow、rembg、python-pptx，需另行安装； 系统需有 ffmpeg（用于视频处理）。

默认配置（可用环境变量覆盖）

变量	默认	说明
MINIO_ENDPOINT	http://localhost:9000	MinIO 地址
MINIO_ACCESS_KEY	minioadmin	MinIO 账号
MINIO_SECRET_KEY	minioadmin	MinIO 密码
MINIO_BUCKET	aidigital	bucket
JAVA_SERVER	http://localhost:48083	Java digital-server（回调用）
ASR_MODEL	medium	faster-whisper 模型
TTS_VOICE	zh-CN-XiaoxiaoNeural	edge-tts 回退音色
MATTING_MODEL	u2net	rembg 抠像模型（u2net / isnet-general-use / birefnet-general）
LIPSYNC_MODEL	wav2lip	口型合成：wav2lip（CPU）/ musetalk（GPU）
WAV2LIP_HOME	空	Wav2Lip 仓库根目录（LIPSYNC_MODEL=wav2lip 时必填）
WAV2LIP_PYTHON	空	Wav2Lip venv 的 python（留空用 <WAV2LIP_HOME>/.venv/bin/python）
WAV2LIP_CHECKPOINT	checkpoints/wav2lip_gan.pth	Wav2Lip 权重路径
WAV2LIP_FACE_DET	face_detection/detection/sfd/s3fd.pth	人脸检测权重
WAV2LIP_BATCH_SIZE	16	推理 batch size
MUSETALK_API	空	MuseTalk 推理服务地址（LIPSYNC_MODEL=musetalk 时必填）
MUSETALK_TIMEOUT	600	MuseTalk 请求超时（秒）
LLM_API_BASE	https://ai-route.huihaohealth.com	LLM 服务（OpenAI 兼容）
LLM_API_KEY	空	LLM 密钥（文案/PPT 生成必填）
LLM_MODEL	claude-opus-4-7-cc	LLM 模型名
PPT_MASTER_ENABLED	空（关）	开启 ppt-master 引擎 /generate_ppt_master（=1 开启）
GPT_SOVITS_API	http://127.0.0.1:9880	GPT-SoVITS 推理 API
GPT_SOVITS_TIMEOUT	120	GPT-SoVITS 请求超时（秒）
GPT_SOVITS_GPT_WEIGHTS	GPT_weights_v2/pretrained.ckpt	预训练基础权重
GPT_SOVITS_SOVITS_WEIGHTS	SoVITS_weights_v2/pretrained.pth	预训练基础权重
WOPI_SECRET	dev-wopi-secret-change-me	WOPI access_token 签名密钥（生产必须改）
WOPI_HOST	http://localhost:60013	CODE 服务端可达的本系统地址（Docker 内访问宿主用 http://host.docker.internal:60013）

接口清单（与 Java 对应）

接口	方法	说明	状态
/ai/formatAudio	POST	声音训练预处理（切片→ASR→上传参考音频，zero-shot）	真实
/tts	GET	声音克隆/合成（GPT-SoVITS，失败回退 edge-tts）	真实
/conflate/makeAudio	POST	声音克隆 POST 变体（edge-tts）	真实
/ai/voice2txt	POST	语音转文字	真实（faster-whisper）
/ai/difyChat	POST	Dify 兼容对话接口（复用本地 LLM）	真实
/ai/humanInteract	POST	数字人互动（TTS + 口型合成）	真实
/aiDhHuman/changeImega	POST	抠图（rembg 出 RGBA PNG）	真实
/aiDhHuman/changeImegaAndViedo	POST	抠图 + 抠像视频（绿幕）	真实
/ai/mergeVideo	POST	视频拼接合成	真实（ffmpeg）
/ai/video_resolution	POST	分辨率/宽高比调整	真实（ffmpeg）
/ai/addCaptions	POST	加字幕（ASS 渲染）	真实（ffmpeg）
/ai/getFirstFrame	POST	提取首帧	真实（ffmpeg）
/ai/changeVideo	POST	语音合成数字人（口型，wav2lip/musetalk）	真实
/ai/changeVideoSplit	POST	语音合成数字人-分段	真实
/ai/deal_video	POST	视频图层合成（背景+数字人+PPT 叠加）	真实（ffmpeg）
/ai/makePptVoice2Video	POST	PPT 语音转视频（参考视频按语音时长循环）	真实
/generate_outline	POST	生成课件提纲	真实（LLM）
/generate_body	POST	生成课件正文	真实（LLM）
/generate_ppt	POST	生成 PPT（LLM→pptx+逐页图片）	真实

端口说明

Java 侧 application-local.yaml 里各接口指向了多个端口（6001/60013/60014/60015/60021/60022/60023/60024/60025/60027）， 对应原来拆分的多个 Python 服务。当前这个 app.py 把所有接口放在一个进程里（默认 60013）。

两种方式对齐：

1. 简单：把 Java 配置里所有 Python 接口的 IP:端口都改成同一个，如 http://localhost:60013。
2. 拆分：用 nginx 按路径反代，或启动多个进程分别监听不同端口并只挂载对应路由。

需要外部资源的能力

这些能力依赖模型权重或外部服务，需按需接入：

• 口型合成 LIPSYNC_MODEL
  • wav2lip（默认，CPU）：克隆 Wav2Lip 仓库并下载权重，配置 WAV2LIP_HOME。
  • musetalk（需 GPU）：部署 MuseTalk 推理服务，配置 MUSETALK_API。
  • 未接入时也可走 wav2lip.change_video_passthrough（只合音轨，不生成口型），用于跑通流程。
• 声音合成 / 声音复刻 GPT_SOVITS_API：部署 GPT-SoVITS 的 api_v2.py（端口 9880，zero-shot TTS，权重见 GPT_SoVITS/configs/tts_infer.yaml）；未接入时 /tts 回退 edge-tts（占位）。
• 文案/PPT 生成：配置 LLM_API_KEY（OpenAI 兼容）。
• ppt-master 引擎 /generate_ppt_master：复用 LLM_API_KEY（同一网关，Anthropic /v1/messages）；引擎已 vendor 到 skills/ppt-master/，依赖见 skills/ppt-master/requirements.txt。默认关闭（PPT_MASTER_ENABLED=1 开启）。内置命令白名单 + 路径沙箱（bash 只放行引擎脚本/只读命令，read/write 限引擎根目录内），但非 OS 级沙箱，仍不建议对公网开放。支持 topic-research（web_search DuckDuckGo + web_fetch 复用 web_to_md.py，无 source 时联网补事实缺口）。
• PPT 转图片 /ppttoimage：需 LibreOffice + PDF 转图片（当前为桩）。

在线编辑（Collabora Online / WOPI）

用浏览器在线编辑生成后的 .pptx（像 PowerPoint 一样直接改文件），本系统实现 WOPI host，把 Collabora 的读写桥接到 MinIO。桌面版 LibreOffice 不能嵌网页，浏览器里用的是 Collabora Online（CODE）。

本地跑通（ssl.enable=false）

docker run -t -d -p 9980:9980 \
  -e 'aliasgroup1=http://192.168.1.4:60013' \
  -e 'username=admin' -e 'password=xxx' \
  -e 'extra_params=--o:ssl.enable=false' \
  --restart always --cap-add MKNOD \
  --name collabora-code collabora/code

启动本系统时设置（WOPI_HOST 要填 CODE 容器能访问到本系统的地址，即宿主局域网 IP，且与 aliasgroup1 一致）：

WOPI_HOST=http://192.168.1.4:60013 .venv/bin/uvicorn app:app --host 0.0.0.0 --port 60013

编辑流程（跨 3 个项目）

1. 前端「编辑」→ Java /aiDhPpt/open_edit（传 pptId）→ Java 查 pptUrl → 本系统 POST /ppt/open_edit 返回 wopiSrc。
2. 前端拼 CODE 编辑地址（http://localhost:9980/browser/<hash>/cool.html?WOPISrc=...）塞 iframe。
3. 编辑保存 → CODE 回调 PUT /wopi/files/{fileId}/contents → 覆盖 MinIO 里的 .pptx。
4. 退出编辑 → 前端调 Java /aiDhPpt/render_preview → Java 重渲染预览图 + 调本系统 POST /ppt/notes 提取每页 speaker notes → 回写。

说明与坑

• aliasgroup1 端口要写字面量：http://192.168.1.4:60013，不能写 http://192.168.1.4:.*（CODE 会把端口当数字解析，.* 解析失败会丢弃整条 alias）。
• 只关 ssl.enable：不要加 --o:ssl.termination=true（它会让 discovery 广告 https 但容器只跑 http，浏览器报 Failed to fetch/白屏）。
• CODE 未开 CORS：浏览器不能跨域 fetch CODE 的 /hosting/discovery，所以前端把 edit 地址（含构建号 hash）硬编码，别走 discovery fetch。
• 网络：浏览器要能访问 CODE；CODE 要能访问 WOPI_HOST（GetFile/PutFile 是 CODE 服务端发起的）。容器内 localhost 指向容器自己，不是宿主。
• 安全：access_token 由 WOPI_SECRET HMAC 签名、短时过期、绑定 fileId+user，别把 MinIO 凭据暴露给 CODE。
• 锁/版本：锁与版本号均为内存态（单进程），多人协作编辑依赖 LOCK/UNLOCK；重启后丢失。
• 保真度：Collabora 编辑真实 .pptx，但与 PowerPoint 非 100% 一致；ppt-master 生成的复杂母版/SVG 可能走样。
• 两套编辑模型：Collabora 直接改 .pptx 二进制，与现有 fabric→/regenerate_ppt 的「重新生成」不能混用，选一条当主路径。

回调

Python 处理完成后会回调 Java digital-server：

• POST {JAVA_SERVER}/digital-api/system/voiceManager/updateVoice（训练完成，voiceStatus=2）
• POST {JAVA_SERVER}/digital-api/system/voiceManager/updateVoiceBypython（克隆完成，voiceStatus=4，携带 length 音频时长毫秒）
• POST {JAVA_SERVER}/digital-api/system/aiDhHuman/callBackAiDhHuman（抠图完成/失败，status=3/4）
• POST {JAVA_SERVER}/digital-api/system/aiDhHumanVideo/updateRecordVideo（视频处理各步骤，execStatus=1/2）

背景图脚本

批量下载免费背景图并上传 MinIO、输出入库 SQL：

python scripts/download_backgrounds.py --source picsum --count 12
python scripts/download_backgrounds.py --source unsplash --keyword "minimal business background" --count 12
python scripts/download_backgrounds.py --source pexels --keyword "minimal background" --count 12

unsplash / pexels 分别需要 UNSPLASH_ACCESS_KEY / PEXELS_API_KEY 环境变量。