joshxt/ezlocalai

ezlocalai

镜像概述和主要用途

ezlocalai是一款易于设置的人工智能服务器，允许用户从本地计算机轻松运行多模态人工智能。它旨在简化本地模型的启动流程，自动处理模型下载并根据CPU、RAM和GPU规格配置服务器。该镜像包含OpenAI风格端点，可作为任何模型的OpenAI API代理与其他应用集成，还内置语音克隆文本转语音、语音转文本功能以及完全离线的图像生成能力。

核心功能和特性

• 自动模型管理：根据硬件规格自动下载和配置模型
• 多模态支持：集成文本、图像、语音处理能力
• OpenAI兼容API：提供与OpenAI API一致的端点，便于应用集成
• 语音处理：支持语音克隆（TTS）和语音转文本（STT）
• 图像生成：初始设置后可完全离线生成图像
• 分布式 fallback：多实例资源不足时自动 fallback 到其他实例或OpenAI兼容API
• 专用语音服务器：可将语音处理任务卸载到专用服务器
• 唤醒词检测与训练：支持自定义唤醒词模型训练和多平台部署

使用场景和适用范围

• 本地AI开发：无需依赖云端服务，在本地开发和测试AI应用
• 离线应用部署：适用于网络不稳定或需要数据隐私的环境
• 多模态交互系统：构建包含文本、语音、图像交互的AI助手
• 混合部署架构：结合本地实例与云端API，优化资源利用
• 边缘设备集成：支持生成适用于ESP32等微控制器的唤醒词模型

详细使用方法和配置说明

前提条件

• Python 3.10+
• Docker Desktop (Windows或Mac)
• https://developer.nvidia.com/cuda-12-4-0-download-archive (仅NVIDIA GPU)
• ROCm (仅AMD GPU - Linux)

Linux额外前提条件

• Docker
• Docker Compose
• https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html (仅NVIDIA GPU)
• ROCm (仅AMD GPU - Radeon RX 6000/7000/9000系列、Radeon PRO和Ryzen APU)

快速启动（推荐）

安装CLI并通过单命令启动ezlocalai：

bash
pip install ezlocalai
ezlocalai start

首次运行时需要几分钟下载模型。运行后，可通过http://localhost:8091访问API。

CLI命令

bash
# 使用默认配置启动（自动检测GPU，使用Qwen3-VL-4B）
ezlocalai start

# 使用特定模型启动
ezlocalai start --model unsloth/gemma-3-4b-it-GGUF

# 使用自定义选项启动
ezlocalai start --model unsloth/Qwen3-VL-4B-Instruct-GGUF \
                --uri http://localhost:8091 \
                --api-key my-secret-key \
                --ngrok <your-ngrok-token>

# 其他命令
ezlocalai stop      # 停止容器
ezlocalai restart   # 重启容器
ezlocalai status    # 检查运行状态并显示配置
ezlocalai logs      # 显示容器日志（使用-f参数实时跟踪）
ezlocalai update    # 拉取/重建最新镜像

# 直接从CLI发送提示
ezlocalai prompt "Hello, world!"
ezlocalai prompt "这张图片里有什么？" -image ./photo.jpg
ezlocalai prompt "解释量子计算" -m unsloth/Qwen3-VL-4B-Instruct-GGUF -temp 0.7

CLI选项

提示命令选项

对于其他选项（如Whisper、图像模型等），编辑~/.ezlocalai/.env文件。

数据持久化

所有数据存储在~/.ezlocalai/目录：

模型在容器更新时会保留，更新CLI或重建CUDA镜像时无需重新下载。

基准测试

在Intel i9-***KS + RTX 4090 (24GB)上的性能测试：

两个模型均在启动时预校准，热切换时间约1秒。

分布式Fallback / 多机设置

ezlocalai支持分布式fallback系统，当本地资源（VRAM/RAM）耗尽时，多个实例可相互fallback，或fallback到任何OpenAI兼容API。这实现了：

• 负载均衡：当一台机器繁忙时，请求自动路由到另一台
• 冗余：若一台服务器过载，fallback服务器处理请求
• 资源优化：每台机器处理力所能及的任务，转发其余任务
• 混合部署：混合本地ezlocalai实例与云端API

配置

在.env文件中设置以下环境变量或传递给容器：

bash
# Fallback服务器URL - 可以是另一个ezlocalai实例或任何OpenAI兼容API
FALLBACK_SERVER=http://192.168.1.100:8091  # 另一个ezlocalai实例
# 或使用云服务提供商：
# FALLBACK_SERVER=https://api.openai.com/v1

# Fallback服务器认证
FALLBACK_API_KEY=your-api-key

# 可选：覆盖OpenAI兼容fallback的模型（默认传递原始请求模型）
# 如果未设置，原始请求的模型将传递给fallback服务器
# FALLBACK_MODEL=gpt-4o-mini

# 组合内存阈值（VRAM + RAM），单位GB - 低于此值时触发fallback
# 模型可卸载到系统RAM，因此组合内存比单独VRAM更准确
FALLBACK_MEMORY_THRESHOLD=8.0

系统通过检查/v1/resources端点自动检测FALLBACK_SERVER是另一个ezlocalai实例还是OpenAI兼容API。若是ezlocalai服务器，使用完整端点转发（保留原始请求）；否则fallback到标准OpenAI API调用，传递原始请求模型（或使用FALLBACK_MODEL覆盖）。

示例：双机设置

机器A（带RTX 4090的主服务器）：

bash
EZLOCALAI_URL=http://0.0.0.0:8091
EZLOCALAI_API_KEY=shared-key
FALLBACK_SERVER=http://machine-b:8091
FALLBACK_API_KEY=shared-key

机器B（带RTX 3080的fallback服务器）：

bash
EZLOCALAI_URL=http://0.0.0.0:8091
EZLOCALAI_API_KEY=shared-key
FALLBACK_SERVER=http://machine-a:8091
FALLBACK_API_KEY=shared-key

两台机器相互fallback，形成弹性双节点集群。

示例：本地+云端混合

运行本地ezlocalai并以OpenAI为fallback：

bash
EZLOCALAI_URL=http://0.0.0.0:8091
FALLBACK_SERVER=https://api.openai.com/v1
FALLBACK_API_KEY=sk-your-openai-key
FALLBACK_MODEL=gpt-4o-mini

监控Fallback状态

通过API检查fallback状态：

bash
# 获取资源状态，包括fallback信息
curl http://localhost:8091/v1/resources

# 检查fallback可用性和模型
curl http://localhost:8091/v1/fallback/status

转发内容

当fallback到另一个ezlocalai实例时，自动转发以下端点：

• /v1/chat/completions - 聊天补全（包括流式传输）
• /v1/completions - 文本补全
• /v1/embeddings - 文本嵌入
• /v1/audio/transcriptions - 语音转文本
• /v1/audio/speech - 文本转语音
• /v1/images/generations - 图像生成

对于OpenAI兼容API，仅转发聊天补全和嵌入。

专用语音服务器

ezlocalai支持将TTS（文本转语音）和STT（语音转文本）处理卸载到专用语音服务器。这在以下场景特别有用：

• 分离工作负载：在专用GPU上运行语音模型，主服务器处理LLM
• 优化资源：在有空闲VRAM的服务器上始终加载语音模型
• 减少延迟：避免语音请求的延迟加载

配置

设置VOICE_SERVER环境变量：

bash
# 选项1：指向另一台ezlocalai服务器进行语音处理
VOICE_SERVER=http://192.168.1.100:8091
VOICE_SERVER_API_KEY=your-api-key  # 可选，未设置时使用EZLOCALAI_API_KEY

# 选项2：将此服务器设为语音服务器（保持TTS/STT加载）
VOICE_SERVER=true

语音服务器模式（VOICE_SERVER=true）

设为true时，服务器成为专用语音服务器：

• TTS（Chatterbox）和STT（Whisper）模型在启动时预加载并常驻内存
• 语音模型在请求后永不卸载（无延迟加载/卸载周期）
• LLM模型仍按需延迟加载
• 适合为语音处理配备专用GPU的辅助服务器

语音透传模式（VOICE_SERVER=<url>）

设为URL时，语音请求转发到该服务器：

• TTS和STT请求首先尝试语音服务器
• 若语音服务器故障或不可用，fallback到本地处理
• LLM模型照常本地运行
• 除非语音服务器不可用，否则本地不加载语音模型

示例：双机语音卸载设置

机器A（带RTX 4090的主LLM服务器）：

bash
DEFAULT_MODEL=unsloth/Qwen3-Coder-30B-GGUF
VOICE_SERVER=http://machine-b:8091
VOICE_SERVER_API_KEY=shared-key

机器B（带RTX 3090的语音服务器）：

bash
DEFAULT_MODEL=unsloth/Qwen3-4B-Instruct-GGUF  # 用于基本任务的小型LLM
VOICE_SERVER=true  # 保持语音模型加载

机器A处理LLM推理，机器B处理所有语音处理，模型始终就绪。

唤醒词检测与训练

ezlocalai包含完整的唤醒词训练和推理系统，支持AI助手的自定义语音激活。当VOICE_SERVER=true时，唤醒词端点启用。

自定义唤醒词架构

ezlocalai使用TTS生成样本训练唤醒词模型，并导出多种格式用于跨平台部署：

mermaid
graph LR
    A[用户选择唤醒词] --> B[ezlocalai训练模型]
    B --> C[导出: PyTorch .pt]
    B --> D[导出: ONNX .onnx]
    B --> E[导出: ESPDL .espdl]
    C --> F[服务器推理]
    D --> G[移动应用<br/>ONNX Runtime Mobile]
    E --> H[ESP32-S3<br/>ESP-DL Framework]

支持的导出格式

ESPDL格式量化为int8，用于微控制器上的高效推理，模型大小减少约75%同时保持准确性。

模型架构

• 输入：40个MFCC系数 × 150帧（16kHz音频的1.5秒）
• 架构：带3个卷积层+批归一化+最大池化的紧凑型CNN
• 输出：单个sigmoid概率 [0.0, 1.0]
• 典型准确率：95-98%验证准确率

API端点

bash
# 训练新唤醒词模型
curl -X POST "http://localhost:8091/v1/wakeword/train" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"word": "hey jarvis"}'

# 检查训练状态
curl "http://localhost:8091/v1/wakeword/jobs/{job_id}" \
  -H "Authorization: Bearer your-api-key"

# 列出可用模型
curl "http://localhost:8091/v1/wakeword/models" \
  -H "Authorization: Bearer your-api-key"

# 下载移动模型（ONNX格式）
curl "http://localhost:8091/v1/wakeword/models/hey%20jarvis?format=onnx" \
  -H "Authorization: Bearer your-api-key" \
  -o hey_jarvis_model.onnx

# 下载ESP32-S3模型（ESPDL格式）
curl "http://localhost:8091/v1/wakeword/models/hey%20jarvis?format=espdl" \
  -H "Authorization: Bearer your-api-key" \
  -o hey_jarvis_model.espdl

# 下载服务器端推理的PyTorch模型
curl "http://localhost:8091/v1/wakeword/models/hey%20jarvis?format=pytorch" \
  -H "Authorization: Bearer your-api-key" \
  -o hey_jarvis_model.pt

客户端集成

移动应用（Flutter/Dart）：

dart
// 从ezlocalai下载模型
final response = await http.get(
  Uri.parse('$serverUrl/v1/wakeword/models/$wakeWord?format=onnx'),
  headers: {'Authorization': 'Bearer $apiKey'},
);
// 使用ONNX Runtime Mobile保存和加载
final session = await OrtSession.create(modelPath);

ESP32-S3（C with ESP-DL）：

c
#include "custom_wakeword.h"

// 初始化自定义唤醒词系统
custom_wakeword_init();

// 从服务器下载模型（存储在NVS中）
custom_wakeword_download_model(
    "[***]