LocalAI LongCat-Video 后端深度指南文本/图像生成视频与 Audio-to-Avatar 数字人推理实现【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAILongCat-Video 是 LocalAI 中一个仅面向 NVIDIA CUDA GPU的 Python 视频生成后端通过GenerateVideogRPC 接口服务美团开源的LongCat-Video文生视频 / 图生视频与LongCat-Video-Avatar-1.5音频驱动数字人两类权重。阅读本文你将掌握如何在 LocalAI Model Gallery 中安装这两套模型、理解全部模型加载选项与逐请求参数的真实取值范围、Base 与 Avatar 两类推理管线的内部流程含多段续写机制以及 SDPA 注意力回退补丁为何能让后端跑在没有 FlashAttention 的 CUDA 13 ARM64 机器如 NVIDIA DGX Spark上。核心依据是仓库内的 后端说明文档并结合 backend.py、longcat_utils.py、gallery/index.yaml 等源码逐条印证。一、后端定位与能力总览longcat-video是 backend/python/longcat-video 目录下的一个独立 Python 后端进程。它与 LocalAI 主进程通过 gRPC 通信服务端与客户端协议定义在 backend/backend.proto 中。后端对外暴露三类核心能力文生视频 / 图生视频使用LongCat-VideoBase检查点输入文本提示词或叠加一张起始帧图像生成短视频音频 文本 → 数字人、肖像 音频 → 数字人使用LongCat-Video-Avatar-1.5Avatar 1.5输入语音与提示词可输出与语音口型同步的头像视频支持用一张肖像图约束外观多段 Avatar 续写当语音时长超过单个生成段容量时后端自动把视频切分为多个连续段segment逐段续写再把各段拼接为与完整音频时长匹配的视频PyTorch SDPA 注意力回退当 FlashAttention 不可用例如 CUDA 13 的 ARM64 平台时通过补丁补齐 SDPA 分支保证在没有 FA2/FA3 的硬件上仍可推理。两类模型的判别后端只接受两个特定检查点不接受任意目录或仓库。分类逻辑位于 longcat_utils.py 的classify_model若传入路径指向本地目录则读取该目录下model_index.json或config.json中的model_name字段做判断若传入仓库标识则仅接受精确匹配meituan-longcat/LongCat-Video判为base或meituan-longcat/LongCat-Video-Avatar-1.5判为avatar的字符串也接受hf://、huggingface://前缀与https://huggingface.co/...URL 形式见normalize_model_source。LoadModel收到不支持的检查点时会以INVALID_ARGUMENT直接拒绝longcat-video only accepts LongCat-Video or LongCat-Video-Avatar-1.5 checkpoints见 backend.py。二、安装Model Gallery 一键拉取与源码手动构建2.1 Model Gallery 安装推荐LocalAI 把两个检查点包装成了 gallery recipe可直接安装入口位于 gallery/index.yamllongcat-videogallery/index.yaml权重源为meituan-longcat/LongCat-Videogallery 描述中指出它在 Hugging Face 存储上约 83 GB要求 Linux NVIDIA CUDA GPU 以及充足的内存与磁盘longcat-video-avatar-1.5gallery/index.yaml权重源为meituan-longcat/LongCat-Video-Avatar-1.5并且额外把LongCat-Video声明为一个companion伴随工件因为 Avatar 需要从 Base 检查点里复用 tokenizer、text encoder 与 VAE 组件。两个条目的overrides都强制指定backend: longcat-video并分别声明了输入输出模态详见第五节。安装时 LocalAI 会按条目的artifacts中的allow_patterns做部分下载例如 Avatar 只拉取base_model/**、scheduler/**、whisper-large-v3/**、lora/dmd_lora.safetensors等而不是整个仓库全量拉取。2.2 源码级手动构建进阶后端自带一整套 shell 构建脚本。上游源码的版本被固定死pin在 Makefile 中并在构建期打上本地补丁LONGCAT_VIDEO_VERSION?6b3f4b8582a8bc3f20f795735f5383716c4ba794 LONGCAT_VIDEO_REPO?https://github.com/meituan-longcat/LongCat-Video LONGCAT_SOURCE_STAMPsources/LongCat-Video/.localai-$(LONGCAT_VIDEO_VERSION) $(LONGCAT_SOURCE_STAMP): patches/0001-sdpa-attention-fallback.patch ... git fetch --depth 1 origin $(LONGCAT_VIDEO_VERSION) \ git checkout --detach FETCH_HEAD \ git apply ../../patches/0001-sdpa-attention-fallback.patch \ ...上述内容见 Makefile。在 backend/python/longcat-video 目录下可执行make拉取固定 commit6b3f4b8…并执行 install.sh其内部会调用common/libbackend.sh的installRequirements按 Python 3.12 独立环境安装依赖make run安装后启动 gRPC 服务run.sh →startBackend默认监听localhost:50051可由--addr覆盖见 backend.pymake test运行单元测试 test.py。Makefile 中的注释和 README 都强调补丁只补齐缺失的 SDPA 注意力分支模型与源码许可证保持 MIT 不变。三、模型加载选项Model Options后端把模型级选项集中在一个白名单中attention_backend、base_model、max_segments、resolution、use_distill、use_int8见 backend.py 的LOAD_OPTIONS。下表在 README 原表基础上补充了在 backend.py 与 longcat_utils.py 中实际可见的取值边界与校验规则选项默认值说明与可取值attention_backendsdpa注意力实现sdpa、auto、flash2、flash3或xformers。仓库随附的打包后端只保证sdpa。各值会被翻译为enable_flashattn2/enable_flashattn3/enable_xformers三组布尔开关见ATTENTION_OVERRIDES非法值会直接抛错attention_backend must be one of: ...。use_distillAvatar 为trueBase 为false是否加载检查点自带的加速蒸馏 LoRA。Base 加载lora/cfg_step_lora.safetensors见 backend.pyAvatar 加载lora/dmd_lora.safetensorslora_network_dim128、lora_network_alpha64见 backend.py。开启后推理步数与引导尺度自动切换为蒸馏模式。use_int8false仅 Avatar 1.5 支持加载其base_model_int8/下的 INT8 量化 DiT见 backend.py。若对 Base 模型设置use_int8:true会抛错use_int8 is supported only by LongCat-Video-Avatar-1.5。对统一内存架构而言BF16 反而有更低的加载期峰值占用。base_modelmeituan-longcat/LongCat-VideoAvatar 1.5 复用的 Base 组件来源必须是LongCat-Video检查点否则报base_model must point to a LongCat-Video checkpoint。可为本地目录或 HF 仓库由_resolve_option_path统一解析见 backend.py。max_segments8单个请求允许的最大 Avatar 续写段数范围1..64。请求所需段数超过该上限时会被拒绝并提示调整音频或提高本选项。resolution480p图像条件生成分辨率480p或720p。_resolution与LoadModel两处都会校验非法值报resolution must be 480p or 720p。选项通过key:value字符串形式解析无冒号视为布尔true标志值会依次尝试解析为布尔 / 整数 / 浮点 / 字符串见 longcat_utils.py 的parse_options。需要注意的是LocalAI 主进程会把 llama.cpp 风格的服务默认项如cache_reuse、parallel注入到每一个模型配置上因此LoadModel通过select_known_options把未知键忽略而非报错只打日志见 backend.py。四、请求级参数与视频生成接口4.1 GenerateVideoRequest 公共字段所有视频生成统一走GenerateVideoRPC请求结构定义在 backend.protoprompt、negative_prompt、start_image、end_image、width、height、num_frames、fps、seed、cfg_scale、step、dst输出路径、audio已暂存的音频路径以及params后端专属逐请求参数值一律为字符串由后端自行校验与强转。HTTP 层对应POST /video端点其请求体结构见 core/schema/localai.go 的VideoRequest媒体start_image、audio等可以是公网 URL、base64 或data:URILocalAI 在 core/http/endpoints/localai/video.go 中负责校验、下载与暂存单个输入媒体上限为 128 MBmaxVideoInputBytes 128 20。4.2 逐请求 params 详解README 指出params可携带num_segments、audio_guidance_scale、offload_kv_cache、ref_img_index、mask_frame_range、resolution白名单对应 backend.py 的REQUEST_PARAMS。下表补充了各自的作用位置与真实边界依据 backend.py参数默认说明与边界num_segments由音频或帧数推导显式指定 Avatar 续写段数最小 1。未指定时若num_frames 0按帧数换算1 ceil((frames - 93) / 80)否则按音频时长换算avatar_segments_for_duration默认 25fps。audio_guidance_scale4.0蒸馏模式固定1.0Avatar 音频引导尺度范围0.0..20.0。offload_kv_cachefalse多段续写时是否在每段结束后卸载 KV cache布尔。ref_img_index10参考帧索引把首帧潜变量回注为参考的时序偏移范围-30..30。mask_frame_range3续写时对重叠区做 mask 的帧数范围0..32。resolution继承模型选项图像条件生成的480p/720p仅当请求带了起始帧图像时生效。4.3 Base 模型的 T2V / I2V 推理_generate_basebackend.py处理文生视频generate_t2v与图生视频generate_i2v行为完全由是否蒸馏决定蒸馏模式use_distilltruenum_inference_steps固定 16cfg_scale强制 1.0非蒸馏模式步数默认 50范围 1..200CFG 默认 4.0范围 0.0..30.0fps默认 15范围 1..60seed 0时回退到 42negative_prompt为空时使用内置默认负向提示词防特写、过曝、模糊、坏手、坏脸、画面停滞等见 backend.py帧数会先经normalize_num_frames对齐到(n-1)/4*41的时序形状默认 93 帧见 longcat_utils.py文生视频的分辨率由width/height决定validate_dimensions默认 832×480宽高各自不小于 256、不超过 1280×768、必须 16 对齐且总像素不超过 1280×768见 longcat_utils.py图生视频则由resolution选项决定。Base 管线明确不支持end_image条件见 backend.py请求携带audio也会被拒绝因为音频输入只属于 Avatar 模型。4.4 Avatar 1.5 的 AT2V / AI2V 与多段续写_generate_avatarbackend.py是全部实现中最复杂的部分体现 README 所称的“audio text-to-avatar、portrait audio-to-avatar、多段续写”三件事音频前置处理用 librosa 把输入语音重采样为 16 kHz 单声道若为空样本直接报错。随后用检查点自带的whisper-large-v3音频编码器产出整段语音嵌入非有限值会触发audio encoder returned non-finite values校验。分段时间几何每段固定 93 帧、重叠 13 个条件帧、25fps。对每个待生成帧取语音嵌入中 ±2 帧窗口作为该帧的音频条件audio_window生成时长不足语音时长时在语音尾部补零对齐。逐段生成第一段走generate_ai2v带肖像或generate_at2v纯文生头像后续段走generate_avcaudio-video continuation复用首帧潜变量作为参考use_kv_cachetrue携带上一段 KV并依据offload_kv_cache决定是否释放。enhance_hf仅在非蒸馏模式下为真。拼接输出每段丢弃与上一段重叠的 13 个条件帧后追加最后把所有帧与原始音频用 ffmpeg 合流视频流 copy、AAC 192 kbps、-shortest见_save_avatar_videobackend.py。无论 Base 还是 Avatar生成的视频统一由 imageio 以 H.264libx264、crf 18、yuv420p、faststart写为 MP4见_save_videobackend.py。后端还实现了客户端取消中断pipeline._interrupt与请求结束后的释放清理_release_model会gc.collect()并清空 CUDA 缓存。五、模态声明与 Base 伴随工件机制README 特别强调gallery 条目与导入配置中必须声明known_input_modalities/known_output_modalities手动编写的模型配置也应保留这些声明。它们的作用是让 LocalAI 的模型发现机制无需探测后端进程或检查点文件名就能区分 Base 的“图像条件视频”与 Avatar 的“音频条件”Baseknown_input_modalities: [text, image]、known_output_modalities: [video]Avatar 1.5known_input_modalities: [text, image, audio]、known_output_modalities: [video]。以 gallery/index.yaml 的 Base 条目为参照一个等价的手写模型配置可以写成name: longcat-video backend: longcat-video known_usecases: - video known_input_modalities: - text - image known_output_modalities: - video options: attention_backend: sdpa parameters: model: meituan-longcat/LongCat-VideoAvatar 条目再追加audio模态、use_distill: true选项并把LongCat-Video声明为 companion 工件。这一机制不只是组织问题而是分布式部署的关键把 Base 仓库声明为 companion 后LocalAI 会在前端就获取两份权重远端 worker 接手的是已暂存staged好的权重快照而不必在加载时限内自行下载。gallery 注释还点明allow_patterns应与实际选项匹配——Avatar 仓库同时携带base_model/与base_model_int8/但任一时刻只会读取其中一个若不设限制将近似双倍下载若在本条目上启用use_int8还需额外把base_model_int8/**加入模式gallery/index.yaml。相关 import 逻辑可参看 core/gallery/importers/longcat-video.go其LongCatVideoImporter是刻意限定 owner/repository 的专属 importer。六、SDPA 回退补丁为什么能跑在 DGX Spark 上上游 LongCat-Video 原生依赖 FlashAttention而 CUDA 13 的 ARM64 平台例如 NVIDIA DGX Spark没有可用的 FlashAttention 内核。仓库在构建期用 patches/0001-sdpa-attention-fallback.patch 为 Base 与 Avatar 两套注意力模块补齐缺失的 SDPA 分支且仅此而已许可证保持 MIT。该设计在注意力开关层面闭环attention_backend五个取值会映射成enable_flashattn2/enable_flashattn3/enable_xformers的组合longcat_utils.pysdpa即三者全关这些开关在加载 DiT 时作为**overrides传入例如 backend.py。数值正确性由 test.py 中的SDPAFallbackTest验证Base 与 Avatar 的自注意力在 SDPA 模式下与手工softmax(Q·Kᵀ)·V参考实现的绝对误差小于1e-4交叉注意力的分块对角行为也有专门断言。测试同时覆盖了parse_options标量强转、未知选项忽略、classify_model只接受受支持模型、帧数与段数的对齐换算、分辨率边界、注意力非法值拒绝等行为LongCatUtilsTest。注意力相关测试依赖打补丁后的上游源码与 triton未满足条件时会被unittest.skipUnless跳过。七、硬件前提与部署约束README 明确列出的部署边界与代码校验一一对应CUDA-only后端在加载时校验torch.cuda.is_available()不可用则返回FAILED_PRECONDITIONlongcat-video requires an NVIDIA CUDA GPUbackend.py无 CPU / macOS 后端镜像发布仓库没有发布非 CUDA 的运行镜像单进程单卡TensorParallelSize 1会被显式拒绝UNIMPLEMENTED提示currently supports one GPU per backend process存储与内存要求高Base 权重在 HF 上约 83 GBAvatar 还需额外加载 Base 的 tokenizer、text encoder、VAE并叠加 whisper-large-v3 音频编码器。gallery 与 README 都建议预留充足的统一内存unified memory与磁盘。Avatar 在加载时会用文件方式初始化一个 rank 0 / world size 1 的 NCCL 进程组并调用context_parallel_util.init_context_parallel也就是说即便单卡也会走官方的分布式初始化路径backend.py。典型的 Base 图生视频请求体HTTPPOST /video示意如下{ model: longcat-video, prompt: a red fox running across a snowy meadow, cinematic lighting, start_image: https://example.com/first-frame.png, num_frames: 93, fps: 15, seed: 42, params: { attention_backend: sdpa } }Avatar 请求则在上述结构上追加audioURL 或 base64并可透传音频侧参数{ model: longcat-video-avatar-1.5, prompt: a friendly host speaking to camera, start_image: https://example.com/portrait.png, audio: https://example.com/speech.mp3, params: { audio_guidance_scale: 4.0, offload_kv_cache: false, ref_img_index: 10, mask_frame_range: 3 } }以上 JSON 字段与 core/schema/localai.go 的 HTTP 结构一致底层再被翻译为GenerateVideoRequest转发给本后端。若num_frames按 25fps × 语音时长换算出的段数超过模型的max_segments后端会报错并建议裁短音频或调大该选项。八、结语与源码地图围绕 backend/python/longcat-video/README.md 展开的这张地图覆盖了从安装到推理的完整链路Model Gallery 条目负责下载与模态声明gRPC 服务端负责加载与生成SDPA 补丁解决无 FlashAttention 硬件的兼容问题而 Base Avatar 的差异化管线让 LocalAI 用一个GenerateVideoRPC 同时支撑文生视频与音频驱动的数字人。如需进一步阅读源码建议按以下顺序深入协议与 HTTP 层backend/backend.proto、core/schema/localai.go、core/http/endpoints/localai/video.go后端实现backend.py加载与推理、longcat_utils.py解析与校验构建与补丁Makefile、patches/0001-sdpa-attention-fallback.patch、install.sh、run.sh验证test.py模型分发与模态声明gallery/index.yaml、core/gallery/importers/longcat-video.go。【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考