ideogram-ai/ideogram-4-nf4 · Hugging Face

来源：https://huggingface.co/ideogram-ai/ideogram-4-nf4 Ideogram（https://ideogram.ai/）

Ideogram 4：处于设计前沿的开放图像模型

博客文章（https://ideogram.ai/blog/ideogram-4.0/）代码（https://github.com/ideogram-oss/ideogram4）模型（https://huggingface.co/collections/ideogram-ai/ideogram-4）API（https://developer.ideogram.ai/）官方网站（https://ideogram.ai/）

Ideogram 4 样本拼贴，涵盖写实摄影、插画、版式设计和海报设计

Ideogram 4 是 Ideogram（https://ideogram.ai/）的首个开放权重文本转图像模型。它是一个从零开始训练的最先进基础模型——并非对任何现有模型的微调。它引入了全新的结构化 JSON 提示词接口，具备业界领先的多语言文字渲染能力、深度语言理解、显式边界框布局与调色板控制，以及原生 2K 分辨率图像生成。体验该模型最便捷的方式是在线访问 ideogram.ai（https://ideogram.ai/）。

我们相信开放性驱动创新，诚邀研究社区与我们携手共进，共同探索视觉智能的前沿。

https://huggingface.co/ideogram-ai/ideogram-4-nf4#table-of-contents目录

1. 最新动态（https://huggingface.co/ideogram-ai/ideogram-4-nf4#news）
2. 模型库（https://huggingface.co/ideogram-ai/ideogram-4-nf4#model-zoo）
3. 性能表现（https://huggingface.co/ideogram-ai/ideogram-4-nf4#performance）
4. 快速开始（https://huggingface.co/ideogram-ai/ideogram-4-nf4#quick-start）
5. 模型概述（https://huggingface.co/ideogram-ai/ideogram-4-nf4#model-summary）
6. 提示词指南（https://huggingface.co/ideogram-ai/ideogram-4-nf4#prompting-guide）
7. 文档（https://huggingface.co/ideogram-ai/ideogram-4-nf4#documentation）
8. 引用（https://huggingface.co/ideogram-ai/ideogram-4-nf4#citation）

https://huggingface.co/ideogram-ai/ideogram-4-nf4#news最新动态

• [2026-06-03] Ideogram 4 正式发布！ 推理代码和权重现已公开，我们的技术博客文章（https://ideogram.ai/blog/ideogram-4.0/）也已上线。请参阅快速开始（https://huggingface.co/ideogram-ai/ideogram-4-nf4#quick-start）部分生成您的第一张图像，或在 ideogram.ai（https://ideogram.ai/）在线体验该模型。

https://huggingface.co/ideogram-ai/ideogram-4-nf4#model-zoo模型库

我们计划在未来支持更多量化版本。

https://huggingface.co/ideogram-ai/ideogram-4-nf4#performance性能表现

我们在第三方竞技场和基准测试、标准开源基准测试以及我们自己的内部人类偏好基准测试中对 Ideogram 4 进行了全面评估。在所有评估中，Ideogram 4 是目前最优秀的开放权重图像模型，并处于设计领域的前沿。

https://huggingface.co/ideogram-ai/ideogram-4-nf4#design-arenaDesign Arena

Design Arena（https://www.designarena.ai/）是一个专注于设计导向生成的第三方图像 Elo 排行榜。在总榜上，Ideogram 4 是排名最高的开放权重模型，仅次于专有的 GPT 和 Gemini 模型：

Design Arena 图像 Elo 总榜，Ideogram 4.0 为排名最高的开放权重模型

仅筛选开放权重模型时，Ideogram 4 以显著优势领先，远超次优的开放模型：

Design Arena 开放权重图像 Elo 排行榜，Ideogram 4.0 大幅领先所有其他开放模型

https://huggingface.co/ideogram-ai/ideogram-4-nf4#contralabsContraLabs

ContraLabs（https://contralabs.com/research）开展了一项盲测版式评估，由 Contra 平台顶尖设计师中的十名专业设计师担任评审。Ideogram 4 在第一名获得率上领跑，整体上有 47.9% 的时间被选为四款模型中的最佳——远超 Gemini 3.1 Flash Image Preview（Nano Banana 2）的 30.0%、FLUX.2 [max] 的 15.5% 以及 Grok Imagine 1.0 的 15.0%：

ContraLabs 版式设计第一名获得率，Ideogram v4 领跑

在实际可用性方面同样胜出：当被问及“您会在真实客户项目中使用它吗？“时，同样的设计师对 Ideogram 4 的评分最高，达到 3.55/5——显著高于 Nano Banana 2（2.84）、Grok Imagine 1.0（2.61）和 FLUX.2 [max]（2.49）：

ContraLabs “您会在真实客户项目中使用它吗？“评分，Ideogram v4 领跑

https://huggingface.co/ideogram-ai/ideogram-4-nf4#lmarenaLMArena

在 LMArena（https://lmarena.ai/）——一个衡量通用文本转图像用例的第三方排行榜——上，Ideogram 是排名最高的开放权重实验室，也是整体排名前五的图像生成实验室——仅次于预算和资源远超我们的大型企业：

LMArena 文本转图像实验室排行榜（含 Ideogram）

https://huggingface.co/ideogram-ai/ideogram-4-nf4#ideogram-internal-evalIdeogram 内部评估

在我们专注于平面设计和摄影的内部人类偏好基准测试中，我们让深度熟悉专业设计工作的平面设计师进行盲测评分。Bradley-Terry 分数将 Ideogram 4 整体排名第二——仅次于 GPT Image 2 medium——并位列开放权重模型之首：

Ideogram 内部设计排行榜（含 Ideogram 4.0）

https://huggingface.co/ideogram-ai/ideogram-4-nf4#open-source-benchmarks开源基准测试

在衡量核心能力的标准开源基准测试中——包括布局控制（7Bench）、空间推理与对象保真度（SpatialGenEval）、文字渲染（X-Omni OCR）以及提示词对齐（Prism）——Ideogram 4 在每个维度上都缩小了与领先闭源模型的差距。在布局控制（7Bench）方面，它显著优于所有闭源模型：

五轴能力雷达图，对比 Ideogram 4.0 与领先闭源模型在布局控制、空间推理、对象保真度、提示词对齐和文字渲染方面的表现

凭借 9.3B 参数，Ideogram 4 在我们基准测试的所有开放权重发布版本中实现了最佳文字渲染效果——超越了参数量更大的 Qwen-Image（20B）、FLUX.2 [dev]（32B）和 HunyuanImage 3.0（80B MoE）：

参数效率散点图，显示 Ideogram 4.0 以 9.3B 参数在文字渲染方面领先所有其他开放权重模型

https://huggingface.co/ideogram-ai/ideogram-4-nf4#quick-start快速开始

https://huggingface.co/ideogram-ai/ideogram-4-nf4#install安装

推理代码位于 ideogram4（https://github.com/ideogram-oss/ideogram4）GitHub 仓库中。克隆后，在仓库根目录执行：

pip install .

如果您计划修改代码，请以可编辑模式安装，这样对 src/ideogram4/ 下的修改无需重新安装即可生效：

pip install -e .

https://huggingface.co/ideogram-ai/ideogram-4-nf4#model-access模型访问

模型权重在 Hugging Face 上设有访问限制，因此您必须接受许可条款并完成身份验证，代码才能下载权重——否则下载将以 404/GatedRepoError 失败。

1. 打开模型页面——ideogram-ai/ideogram-4-nf4（https://huggingface.co/ideogram-ai/ideogram-4-nf4）（或 ideogram-ai/ideogram-4-fp8（https://huggingface.co/ideogram-ai/ideogram-4-fp8））——点击同意并访问仓库以接受许可条款。
2. 在 huggingface.co/settings/tokens（https://huggingface.co/settings/tokens）创建 Hugging Face 访问令牌并登录，以完成下载认证：hf auth login 也可以直接导出令牌：export HF_TOKEN="hf_..."。

https://huggingface.co/ideogram-ai/ideogram-4-nf4#cliCLI

通过 --prompt 传入的普通提示词会由“魔法提示词“LLM 改写为模型所需的结构化 JSON 描述。默认情况下，这一过程使用 Ideogram 的托管魔法提示词 API，该 API 免费且在服务端完成扩展（无需本地模型或系统提示词）。它读取 IDEOGRAM_API_KEY——在 developer.ideogram.ai（https://developer.ideogram.ai/）获取密钥：

python run_inference.py \
  --prompt "a ginger cat wearing a tiny wizard hat reading a spellbook" \
  --output out.png \
  --quantization "nf4" \
  --magic-prompt-key "$IDEOGRAM_API_KEY"

您也可以通过自己的 LLM 提供商运行扩展——我们的一个魔法提示词系统提示词已开源。详见提示词指南（https://github.com/ideogram-oss/ideogram4/blob/main/docs/prompting.md#magic-prompt）。

如需获得最高质量的图像，请设置 --height 2048 --width 2048 和 --sampler-preset V4_QUALITY_48。

https://huggingface.co/ideogram-ai/ideogram-4-nf4#safety-screening-with-hive使用 Hive 进行安全审查

提示词和输出内容的安全审查通过 Hive（https://thehive.ai/）进行。注册并分别创建文本审核密钥和视觉内容审核密钥，然后将其导出为 HIVE_TEXT_MODERATION_KEY 和 HIVE_VISUAL_MODERATION_KEY（或通过 --hive-text-key/--hive-visual-key 传入）。

python run_inference.py \
  --prompt "an isometric illustration of a tiny city floating in the clouds" \
  --output out.png \
  --quantization "nf4" \
  --magic-prompt-key "$MAGIC_PROMPT_API_KEY" \
  --hive-text-key "$HIVE_TEXT_MODERATION_KEY" \
  --hive-visual-key "$HIVE_VISUAL_MODERATION_KEY"

有关采样器预设、参数参考和优化建议，请参阅 docs/inference.md（https://github.com/ideogram-oss/ideogram4/blob/main/docs/inference.md）。

https://huggingface.co/ideogram-ai/ideogram-4-nf4#diffusersdiffusers

本模型已与 🧨 diffusers 库集成。

从 main 分支安装 diffusers：

pip install git+https://github.com/huggingface/diffusers.git

https://huggingface.co/ideogram-ai/ideogram-4-nf4#diffusers—remote-prompt-upsamplingdiffusers - 远程提示词增强

为获得最佳效果，请使用 Ideogram 提示词增强功能：

import json, os, torch, requests
  from diffusers import Ideogram4Pipeline

  pipe = Ideogram4Pipeline.from_pretrained(
      "ideogram-ai/ideogram-4-nf4-diffusers",
      torch_dtype=torch.bfloat16,
      token=os.environ["HF_TOKEN"], # 或：token="hf_xxxxxxxxx"，由于仓库有访问限制，需要提供 token
  ).to("cuda")

  # 使用 Ideogram 免费托管的魔法提示词 API，将提示词扩展为结构化 JSON 描述。
  # 在 https://developer.ideogram.ai/ 获取密钥（设置 IDEOGRAM_API_KEY）。
  resp = requests.post(
      "https://api.ideogram.ai/v1/ideogram-v4/magic-prompt",
      headers={"Api-Key": "your_ideogram_api_key"},
      json={"text_prompt": "a ginger cat wearing a tiny wizard hat reading a spellbook", "aspect_ratio": "1x1"},
  ).json()
  caption = json.dumps(resp["json_prompt"])  # 或：token="hf_xxxxxxxxx"，由于仓库有访问限制，需要提供 token

  # 将描述直接传入 pipeline（无需 prompt_upsampling——已完成增强）。
  image = pipe(
      caption, 
      height=1024, # 模型最高支持 2048
      width=1024, # 模型最高支持 2048
      generator=torch.Generator("cuda").manual_seed(0),
  ).images[0]
  image.save("ideogram4.png")

https://huggingface.co/ideogram-ai/ideogram-4-nf4#diffusers—local-prompt-upsamplingdiffusers - 本地提示词增强

如需完全本地化的体验，diffusers 内置了一个 prompt_upsampling 功能，使用与文本编码器相同的 Qwen3-VL-8B 模型进行增强。相比远程提示词增强，质量会有所下降。

pip install outlines # 用于强制 JSON 结构

import os, torch
 from diffusers import Ideogram4Pipeline, Ideogram4PromptEnhancerHead

 # 使文本编码器（无头版本）具备生成能力的 LM head，作为小型组件加载。
 prompt_enhancer_head = Ideogram4PromptEnhancerHead.from_pretrained(
     "diffusers/qwen3-vl-8b-instruct-lm-head",
     torch_dtype=torch.bfloat16,
 )

 pipe = Ideogram4Pipeline.from_pretrained(
     "ideogram-ai/ideogram-4-nf4-diffusers",
     prompt_enhancer_head=prompt_enhancer_head,
     torch_dtype=torch.bfloat16,
     token=os.environ["HF_TOKEN"], # 或：token="hf_xxxxxxxxx"
 ).to("cuda")

 # prompt_upsampling=True 会在设备本地将提示词改写为 Ideogram 的结构化 JSON 描述
 image = pipe(
     "a ginger cat wearing a tiny wizard hat reading a spellbook",
     height=1024, # 模型最高支持 2048
     width=1024, # 模型最高支持 2048
     prompt_upsampling=True,
     generator=torch.Generator("cuda").manual_seed(0),
 ).images[0]
 image.save("ideogram4.png")

https://huggingface.co/ideogram-ai/ideogram-4-nf4#model-summary模型概述

Ideogram 4 是一个完全从零开始训练的基础模型，并非对任何现有检查点的微调或蒸馏。它是一个基于完全单流扩散 Transformer（DiT）架构构建的流匹配文本转图像模型。

架构：

• 完全单流 DiT。 文本和图像 token 拼接为一个统一序列，通过同一个 34 层 Transformer 处理，不存在独立的文本或图像分支。这使得每一层都能实现深度跨模态交互。
• 视觉语言模型作为文本编码器。 Ideogram 4 使用 Qwen3-VL-8B-Instruct（https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct）——一个完整的视觉语言模型——而非 CLIP 或 T5 这类纯文本编码器，从而提供对视觉概念更为丰富的理解。隐藏状态从 13 个中间层提取并拼接，为模型提供从表层 token 信息到深层组合理解的多尺度语义特征。
• 双分支无分类器引导。 条件（正向）和无条件（负向）分支可独立调优，从而对提示词遵循度和图像质量实现分别控制。
• 灵活分辨率。 原生支持 256 到 2048（16 的倍数）的任意分辨率，宽高比最高可达 6:1。单一模型可处理从方形缩略图到超宽横幅的所有场景，噪声调度随分辨率自动调整。

核心能力：

• 极强的可控性。 Ideogram 4 基于结构化 JSON 描述训练，赋予用户对构图、风格、光线、调色板、版式和空间布局的前所未有的控制力，一切均可通过单个提示词实现。
• 最先进的文字渲染。 Ideogram 4 提供业界领先的图像内文字生成效果（标牌、徽标、说明文字、水印、多行文本），可直接从提示词高保真生成。
• 空间布局控制。 提示词中的边界框坐标支持对主体、文字元素和背景区域进行显式定位。
• 调色板条件控制。 在提示词中指定十六进制颜色，以引导图像的主色调方案。

完整架构细节请参阅 docs/model_architecture.md（https://github.com/ideogram-oss/ideogram4/blob/main/docs/model_architecture.md）。pipeline 各组件的配合方式说明请参阅 docs/pipeline.md（https://github.com/ideogram-oss/ideogram4/blob/main/docs/pipeline.md）。

https://huggingface.co/ideogram-ai/ideogram-4-nf4#prompting-guide提示词指南

Ideogram 4 完全基于结构化 JSON 描述训练。虽然纯文本提示词也能使用，但提供符合我们描述模式的 JSON 对象将获得最佳效果。

关键要点：

• 使用 JSON 提示词以获得最大可控性——模型基于此训练，能够原生理解该结构。
• 调色板条件控制——在风格描述中指定包含十六进制颜色的 colour_palette 数组，以引导图像的色彩方案。
• 宽高比灵活性——Ideogram 4 支持多种宽高比（每边 256 到 2048 范围内的任意 16 的倍数分辨率）。这是实际应用中的关键优势：竖版人像、横向风景、横幅、手机壁纸、社交媒体格式等均可支持。
• 边界框布局——在提示词中指定 bbox 坐标，以显式放置主体、文字元素和背景区域。
• 组合控制——使用带有边界框和逐元素描述的 compositional_deconstruction。