mflux 图像生成路由服务

您正在协助他人使用 mflux 生成图像——这是一个专为 Apple Silicon 构建的原生 MLX 图像生成框架。该服务不通过子进程方式在单台设备上运行 mflux，而是将 mflux 图像生成请求分发至整个设备集群。路由服务会自动选择已加载 mflux 模型、空闲内存最多且 CPU 负载最低的设备执行请求。

为何需要对 mflux 图像生成进行路由

单台设备运行 mflux 图像生成会阻塞其他任务。例如，在 M3 Ultra 上生成一张 1024×1024 分辨率的 mflux 图像约需 18 秒；若代理在此期间发起第二张图像请求，则必须等待。借助集群路由能力，第二个 mflux 请求将被调度至另一台空闲设备执行。

mflux 图像生成还会与大语言模型（LLM）推理任务竞争 GPU 内存资源。该路由服务可感知哪些节点正忙于处理 LLM 请求，并将 mflux 图像生成任务自动导向负载最轻的设备。

零云成本。一台搭载 M4 芯片的 Mac Mini 运行 mflux 后，单次图像生成成本为 $0（仅需一次性硬件投入）。相比之下，DALL-E 单图收费 $0.04。若每日生成 80 张 mflux 图像，则每月可节省 $96。

快速开始使用 mflux

pip install ollama-herd
herd                        # 启动 mflux 图像生成路由服务（端口 11435）
herd-node                   # 在每台运行 mflux 的设备上启动节点服务
uv tool install mflux       # 在各设备上安装 mflux 以支持图像生成

启用 mflux 图像生成功能：

curl -X POST http://localhost:11435/dashboard/api/settings 
  -H "Content-Type: application/json" 
  -d '{"image_generation": true}'

软件包：ollama-herd | 代码仓库：github.com/geeks-accelerator/ollama-herd

使用 mflux 生成图像

curl — mflux 图像生成

# 通过集群路由服务调用 mflux 图像生成
curl -o mflux_output.png http://localhost:11435/api/generate-image 
  -H "Content-Type: application/json" 
  -d '{
    "model": "z-image-turbo",
    "prompt": "a neon-lit Tokyo alley at midnight, cyberpunk aesthetic",
    "width": 1024,
    "height": 1024,
    "steps": 4,
    "quantize": 8
  }'

Python — mflux 图像生成

import httpx

def mflux_generate_image(prompt, mflux_output_path="mflux_output.png", width=1024, height=1024):
    """通过集群路由服务调用 mflux 生成图像。"""
    mflux_resp = httpx.post(
        "http://localhost:11435/api/generate-image",
        json={
            "model": "z-image-turbo",
            "prompt": prompt,
            "width": width,
            "height": height,
            "steps": 4,
            "quantize": 8,
        },
        timeout=120.0,
    )
    mflux_resp.raise_for_status()
    with open(mflux_output_path, "wb") as f:
        f.write(mflux_resp.content)

    mflux_node = mflux_resp.headers.get("X-Fleet-Node", "unknown")
    mflux_time_ms = mflux_resp.headers.get("X-Generation-Time", "?")
    print(f"mflux 图像生成在 {mflux_node} 完成，耗时 {mflux_time_ms}ms")
    return mflux_output_path

JavaScript — mflux 图像生成

async function mfluxGenerateImage(prompt, width = 1024, height = 1024) {
  // 通过集群路由服务调用 mflux 图像生成
  const mflux_resp = await fetch("http://localhost:11435/api/generate-image", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "z-image-turbo", prompt, width, height, steps: 4, quantize: 8,
    }),
  });
  if (!mflux_resp.ok) throw new Error((await mflux_resp.json()).error);
  return Buffer.from(await mflux_resp.arrayBuffer());
}

mflux 图像生成参数说明

mflux 图像生成响应格式

• 200 OK：返回原始 PNG 字节流。Content-Type: image/png
• X-Fleet-Node：实际执行 mflux 图像生成的设备标识
• X-Fleet-Model：所使用的 mflux 模型名称
• X-Generation-Time：mflux 图像生成耗时（毫秒）

可用的 mflux 模型

带请求标签的 mflux 图像生成

可在仪表盘中按项目追踪 mflux 图像生成任务：

curl -o mflux_output.png http://localhost:11435/api/generate-image 
  -H "Content-Type: application/json" 
  -d '{
    "model": "z-image-turbo",
    "prompt": "your prompt for mflux image generation",
    "metadata": {"tags": ["mflux-project", "mflux-content-gen"]}
  }'

本集群还支持以下功能

大语言模型（LLM）推理

curl http://localhost:11435/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{"model":"gpt-oss:120b","messages":[{"role":"user","content":"Hello"}]}'

语音转文字（Speech-to-text）

curl -s http://localhost:11435/api/transcribe 
  -F "audio=@recording.wav" | python3 -m json.tool

向量嵌入（Embeddings）

curl http://localhost:11435/api/embeddings 
  -d '{"model":"nomic-embed-text","prompt":"search query"}'

mflux 图像生成监控

# mflux 图像生成统计信息（最近 24 小时）
curl -s http://localhost:11435/dashboard/api/image-stats | python3 -m json.tool

# 集群健康状态（含 mflux 图像生成活动）
curl -s http://localhost:11435/dashboard/api/health | python3 -m json.tool

仪表盘地址：http://localhost:11435/dashboard —— mflux 图像生成队列将在界面上以 [IMAGE] 标签标识。

完整文档

Agent Setup Guide —— 包含全部 4 类模型（含 mflux）的完整配置参考指南。

Image Generation Guide —— mflux 图像生成 API 的详细技术参考文档。

安全守则

• 未经用户明确确认，不得删除或修改任何 mflux 生成的图像文件。
• 未经用户确认，不得拉取或删除任何 mflux 模型——模型下载体积通常超过 3 GB。
• 不得删除或修改 ~/.fleet-manager/ 目录下的任何文件。
• 若当前无可用的 mflux 图像生成模型，请建议用户安装：uv tool install mflux。