如果有人问我过去一年内容创作领域最值得关注的变化是什么我的答案不是某个大模型版本的升级而是“Agent”这个词从概念炒作变成了真正能落地的生产力工具。尤其在做技术博客、公众号、教程文档这类内容时配图一直是一个让人头疼的环节找图耗时、版权难确认、风格不统一、插图的语义和正文对不上。第5集我们就来专门解决这个问题用 Agent 自动配图把“读文章—想配图—生成图片—插入点位”这条链路全部自动化。先说一个明确判断Agent 自动配图并不是简单“调用一次图片生成 API”而是一个带目标、能拆解、会校验的智能流程。它真正降低的是内容生产中的“视觉编排成本”而不是“点击生成按钮”的那一秒。如果你写过一篇超过 3000 字的技术文章应该能体会写代码只要一小时找一张合适的架构图配图可能要折腾两小时。这中间差的不是工具而是一套能把文本语义翻译成图片提示词的决策机制。这篇文章会沿着一条完整的落地路径展开先从配图痛点讲起说清楚 Agent 在这里承担什么角色然后拆解自动配图的核心原理和系统架构接着给出可运行的代码实现包括环境准备、Agent 主逻辑、图片生成接口调用、质量校验最后是常见问题排查和工程化建议。读完你能跑通一个最小可用的自动配图 Agent并理解怎么把它接入自己的内容生产流程。1. Agent 自动配图到底解决了什么问题配图这件事看着简单真正做起来其实非常琐碎。我自己给技术文章配图时经历过几个阶段最早是去免费图库搜关键词搜出来的图要么风格陈旧要么和文章主题只有弱关联后来尝试截图软件截图遇到流程图、架构图还得自己用画图工具重新画再后来用上了 AI 生图工具输入提示词倒是方便但一个问题随之而来——为文章的十几个段落分别设计并生成风格统一的配图这件事远比想象中耗神。这里的核心矛盾是一篇文章是一个整体图片之间要有视觉一致性图片与文本之间要有语义对齐。而人工操作时这种一致性完全依赖配图者的经验。今天用插画风明天用 3D 渲染风后天换成线条图读者一眼就能看出不是一套图。Agent 自动配图解决的不只是“省时间”而是把配图从“自由发挥”变成了“有流程可循的工程任务”。Agent 会先阅读全文理解每部分的主题和情绪然后统一制定视觉风格和配图数量再逐段生成提示词并调用生图模型最后对生成结果做校验。整个过程里Agent 像一个熟悉你写作习惯的视觉编辑而不是一个只会听指令的绘图机器。这也回答了另一个很实际的问题自动配图适合谁如果你运营技术博客、写课程讲义、做企业知识库、维护开源项目文档或者经常需要把技术方案整理成图文报告Agent 自动配图都值得做一套。反过来如果你只是偶尔发一条朋友圈配图那确实用不上这么重的流程直接用现成的 AI 生图工具或者图库就够了。判断一个自动化方案值不值得做不应该只看“操作时间少了多少”还要看“质量的一致性和可复用性”。Agent 配图方案的价值恰恰在后两点一次写好的配图流程可以反复用在后续所有文章中而且产出的图片风格由同一套提示词策略保证质量下限会明显高于人工随意发挥。2. Agent 配图的核心原理与工作流程想理解 Agent 自动配图首先要跳出“一个函数调用到底”的惯性思维。传统编程里我们要给程序明确每一步指令先读取文本再分割章节硬编码生成提示词最后调图片接口。这套写法的问题在于不同文章的结构千差万别硬编码规则无法适应“这篇是教程那篇是产品发布”的差异。Agent 的做法不一样。它把大模型当作一个“可以自主思考的执行体”我们只给它目标和方法它自己决定怎么行动。这里用到的经典模式是 ReAct也就是 Reasoning Acting。Agent 在一个循环里交替进行“思考—行动—观察”思考根据当前输入决定下一步该做什么。行动调用某个工具比如读取文章、生成提示词、调用生图 API。观察查看工具返回的结果判断是否达到预期目标。如果没有达到目标Agent 就进入下一轮思考调整策略再试。这正是自动配图和普通脚本的本质区别普通脚本出错就停Agent 出错会自我修正。放到自动配图场景一个标准的工作流程包含五个阶段。第一阶段是内容理解。Agent 把整篇文章文本送入大模型提炼出文章主题、各个段落的子主题、文章的语调和风格。这一步的输出是一份“文章结构化摘要”。第二阶段是配图规划。Agent 根据摘要决定配几张图、每张图放在什么位置、每张图要表达什么信息。这里要考虑文章长度和内容的丰富程度。注意配图数量不是越多越好规划的关键是“每张图都有信息增量”。第三阶段是提示词生成。Agent 为每张目标图片编写生图模型能理解的英文提示词同时为了保持风格统一会在一开始就定义一个全局风格标签比如“Tech illustration, flat design, blue color palette”之后每张图的提示词都包含这个风格前缀。第四阶段是图片生成。Agent 调用部署在本地的 Stable Diffusion WebUI API或者云端生图服务将提示词转换成图片。第五阶段是结果校验。Agent 把生成的图片和原始文本一起“理解”一遍判断图片是否贴合语义或者利用 CLIP 这类模型计算图文相关度。如果相关度不够Agent 会调整提示词重新生成。这五个阶段不是一次性能完成的。我在实际实现中倾向于把 Agent 设计成“规划—执行—反思”的三层循环外层负责配图计划内层负责单张图片的生成与重试。理解这个流程后再去看代码就不会被循环调用绕晕。3. 自动配图系统的整体架构设计明确了工作流程接下来要把流程落地成代码架构。一个生产环境可用的自动配图 Agent 至少包含四个模块文本理解模块、决策规划模块、图片生成模块、质量校验模块。再加上一个编排器也就是 Agent 的核心执行引擎。文本理解模块的职责是调用大模型 API把长文本处理成结构化的 JSON 输出。这个模块要处理的关键问题是输入长度。一篇文章可能有三五千字直接塞给模型做理解不是不行但为了控制成本和提升响应速度通常会先做分段处理再逐段提取要点。决策规划模块是整个系统的“大脑”。它接收文本理解的输出结合用户配置的偏好输出配图计划包括图片数量、图中元素、图片风格、插入位置。这个模块决定了整篇文章的配图节奏判断哪一段需要详细图示哪一段可以用简单的装饰图带过。图片生成模块是执行层。我选择对接 Stable Diffusion WebUI 的 API因为它开源、可本地部署而且没有内容合规风险。Stable Diffusion WebUI 启动后会监听一个本地端口只要向这个端口发送 txt2img 请求就能返回生成图片的 base64 数据。质量校验模块容易被忽略但却是保证“自动配图质量下限”的关键。它可以用两种策略一是让大模型根据生成的图片和对应文本来回判断二是调用 CLIP 模型计算图文向量的余弦相似度。前者的优点是理解能力强缺点是多一次大模型调用后者的优点是快缺点是对抽象概念的判断不够准。建议在小成本场景先用大模型校验高频生产场景再引入 CLIP。模块之间通过数据对象通信我定义了几种关键的数据结构ArticleAnalysis表示文章分析结果ImagePlan表示配图计划ImageResult表示单张生成结果。这样解耦的好处是每一步都可以单独调试也可以替换成其他实现比如把 Stable Diffusion WebUI 换成云端生图服务只需要改图片生成模块。整个系统的交互流程可以概括为主程序读入 Markdown 文章交给 Agent 编排器编排器调用文本理解模块得到结构化分析决策规划模块产出配图计划编排器遍历计划逐张调用图片生成模块中途出现失败或校验不通过就触发重试全部完成后返回图片列表和插入建议。接下来我们进入实操。我会用一个完整示例演示这套架构示例基于 Python 实现大模型部分使用 OpenAI SDK 兼容的通用接口生图部分对接本地 Stable Diffusion WebUI。4. 环境准备与依赖安装在动手写代码之前先把运行环境准备好。以下是推荐的环境配置版本以实际安装为准本文重点演示通用思路不绑定某个具体版本。操作系统方面建议 Linux 或 macOSWindows 也可以跑但 Stabel Diffusion WebUI 的本地部署在 Windows 上需要额外注意显卡驱动和路径问题。Python 版本要求 3.9 以上推荐 3.10 或 3.11太新的 Python 版本有时会遇到个别依赖库尚未适配的情况。依赖安装使用 pip。创建一个虚拟环境然后安装以下核心库python -m venv .venv source .venv/bin/activate pip install openai pip install requests pip install python-dotenv pip install pyyaml说明一下每个库的用途openai官方 Python SDK用来调用大模型 API支持通过 base_url 切换兼容服务。requests用来调用 Stable Diffusion WebUI 的 HTTP 接口。python-dotenv用来读取 .env 文件中的密钥配置。pyyaml用来解析配置文件比如文章路径、风格设定、生成参数。大模型的选择上建议用一个上下文长度足够、指令跟随能力强、成本适中的模型。文本理解和提示词生成属于中等难度任务不需要用最强的模型但也不要用能力太弱的模型否则规划阶段会频繁出现逻辑混乱。生图模型的部署有两种方式。第一种是本地部署 Stable Diffusion WebUI优点是免费、可扩展、隐私可控缺点是依赖 GPU生成速度看显卡性能第二种是调用已部署好的云服务优点是省事缺点是要花钱而且每次请求都要经过网络传输生成大图时有等待成本。如果你选择本地部署 Stable Diffusion WebUI安装完成后需要以 API 模式启动python launch.py --api启动成功的标志是终端输出Running on local URL: http://127.0.0.1:7860。后续示例代码会向这个地址的/sdapi/v1/txt2img接口发送 POST 请求。最后在项目根目录创建一个.env文件填入大模型 API 配置LLM_API_KEYsk-your-key-here LLM_BASE_URLhttps://your-endpoint.example.com/v1 LLM_MODELgpt-4o-mini SD_URLhttp://127.0.0.1:7860注意不要把这文件提交到 Git 仓库。.gitignore里务必加上.env。5. 核心代码实现一个最小可用配图 Agent现在开始写代码。我会按照模块化的方式组织最终形成一个可以直接运行的命令行工具。完整项目结构如下article-agent/ ├── .env ├── requirements.txt ├── config.yaml ├── article.md └── src/ ├── __init__.py ├── main.py ├── agent.py ├── modules/ │ ├── __init__.py │ ├── text_understanding.py │ ├── image_planning.py │ └── image_generation.py └── utils/ ├── __init__.py └── file_utils.py先从最外层的主入口开始理解整体调用关系再逐步看每个模块的实现。5.1 主入口与配置加载main.py负责加载配置、读取文章、调用 Agent并把结果输出为一份配图建议 JSON。为了让流程更清晰我把配置项统一放到config.yaml里和代码分离。# 文件路径src/main.py import os import json import time from dotenv import load_dotenv import yaml from agent import AutoImageAgent from utils.file_utils import read_markdown_article # 加载 .env 文件中的环境变量 load_dotenv() def load_config(config_path: str) - dict: 加载 YAML 配置文件 with open(config_path, r, encodingutf-8) as f: return yaml.safe_load(f) def main(): config_path os.path.join(os.path.dirname(__file__), .., config.yaml) config load_config(config_path) article_path config[article][path] style_config config[style] generation_config config[generation] # 读取要配图的 Markdown 文章 article_text read_markdown_article(article_path) # 初始化 Agent agent AutoImageAgent( llm_api_keyos.getenv(LLM_API_KEY), llm_base_urlos.getenv(LLM_BASE_URL), llm_modelos.getenv(LLM_MODEL), sd_urlos.getenv(SD_URL), style_configstyle_config, generation_configgeneration_config, ) # 执行自动配图流程 start time.time() result agent.run(article_text) elapsed time.time() - start # 输出结果 output { elapsed_seconds: round(elapsed, 2), image_count: len(result[images]), images: result[images], } output_path os.path.join(os.path.dirname(__file__), .., output.json) with open(output_path, w, encodingutf-8) as f: json.dump(output, f, ensure_asciiFalse, indent2) print(f配图完成共生成 {len(result[images])} 张图片耗时 {elapsed:.2f} 秒) if __name__ __main__: main()这段代码本身没有复杂的逻辑它只负责串联。真正的 Agent 行为在agent.py中定义。5.2 配置示例config.yaml的内容如下它集中控制了配图风格和生成参数是调整 Agent 行为的“操作面板”。# 文件路径config.yaml article: path: ./article.md style: # 全局视觉风格描述会拼接到每张图片的提示词前 global_style: Tech illustration, flat design, soft blue gradient background, high contrast, clean composition # 配图模式auto 表示由模型决策fixed 表示固定数量 mode: auto # 当 mode 为 fixed 时生效 fixed_count: 3 generation: width: 768 height: 512 steps: 25 cfg_scale: 7.0 sampler: DPM 2M Karras # 每张图片最大重试次数 max_retries: 2这里的global_style是保持整套配图风格统一的关键。如果不设置这个值模型很可能会给不同段落生成风格差异很大的图片。generation下的参数会被直接透传给生图接口。5.3 Agent 编排器AutoImageAgent类是整套系统的大脑。它把前面说的四个模块串起来实现“分析—规划—生成—校验—重试”的完整循环。为了让逻辑更清晰我没有把校验单独拆成一个类而是把它合并在 Agent 的生成流程里。# 文件路径src/agent.py import re from modules.text_understanding import understand_article from modules.image_planning import create_image_plan from modules.image_generation import generate_image class AutoImageAgent: 自动配图 Agent负责全流程编排 def __init__(self, llm_api_key, llm_base_url, llm_model, sd_url, style_config, generation_config): self.llm_api_key llm_api_key self.llm_base_url llm_base_url self.llm_model llm_model self.sd_url sd_url self.style_config style_config self.generation_config generation_config def run(self, article_text: str) - dict: # 第1步理解文章 analysis understand_article( article_textarticle_text, api_keyself.llm_api_key, base_urlself.llm_base_url, modelself.llm_model, ) # 第2步制定配图计划 plan create_image_plan( analysisanalysis, article_textarticle_text, style_configself.style_config, api_keyself.llm_api_key, base_urlself.llm_base_url, modelself.llm_model, ) # 第3步逐张生成图片失败自动重试 images [] for item in plan: image_info self._generate_with_retry(item) if image_info is not None: images.append(image_info) return {analysis: analysis, images: images, plan: plan} def _generate_with_retry(self, item: dict) - dict | None: 单张图片生成带重试机制 prompt item[prompt] desc item[description] position item[position] max_retries self.generation_config.get(max_retries, 2) for attempt in range(max_retries 1): try: image_data generate_image( promptprompt, sd_urlself.sd_url, widthself.generation_config[width], heightself.generation_config[height], stepsself.generation_config[steps], cfg_scaleself.generation_config[cfg_scale], samplerself.generation_config[sampler], ) return { position: position, description: desc, prompt: prompt, image_base64: image_data, } except Exception as e: print(f第 {attempt 1} 次生成失败: {e}) if attempt max_retries: # 简单策略给提示词追加 more detail 后重试 prompt prompt , more details, better composition else: print(f图片 {position} 生成失败已跳过) return None这里有一个容易踩坑的地方_generate_with_retry中的重试不能无脑执行否则接口如果持续报错整个流程会被拖很长时间。所以我用max_retries控制重试上限超过上限就跳过当前图片继续处理下一张保证整个配图流程不会因为单张图片失败而中断。这个设计在生产环境里很重要。5.4 文本理解模块text_understanding.py负责把文章正文转换成结构化分析结果。实现的思路是让大模型输出 JSON然后用正则从返回内容中提取 JSON 片段。这样做的好处是即使模型偶尔输出了一些前缀解释文字也能容错解析。# 文件路径src/modules/text_understanding.py import json import re from openai import OpenAI ARTICLE_ANALYSIS_PROMPT 你是一名资深的内容编辑。请阅读下面的文章然后输出 JSON 格式的分析结果。 JSON 必须包含以下字段 { topic: 文章的核心主题, tone: 文章的语调和风格, sections: [ { title: 段落或小节的标题, summary: 这一段的核心内容概述, key_elements: [这一段可以配图的关键元素数组每个元素用英文短句描述] } ] } 注意 1. sections 数量控制在 3 到 6 个。 2. key_elements 里的描述要具体不要写 technology 这种抽象词要写 a laptop with code on screen 这样的具象描述。 3. 只输出 JSON不要输出其他解释。 文章内容如下 {article_text} def understand_article(article_text: str, api_key: str, base_url: str, model: str) - dict: client OpenAI(api_keyapi_key, base_urlbase_url) prompt ARTICLE_ANALYSIS_PROMPT.format(article_textarticle_text[:6000]) response client.chat.completions.create( modelmodel, messages[{role: user, content: prompt}], temperature0.3, ) content response.choices[0].message.content # 提取 JSON 片段 match re.search(r\{.*\}, content, re.DOTALL) if not match: raise ValueError(模型输出未包含有效 JSON) return json.loads(match.group())注意article_text[:6000]这个截断操作是临时的简化处理。如果文章很长更好的做法是把文章按标题拆分成多个片段分别分析再合并结果。后面第 8 节我会展开讲优化思路。5.5 配图规划模块image_planning.py生成具体的配图计划。它会基于文本理解的结果结合用户配置的风格信息为每个 section 决定是否配图以及配什么样的图。我在这个模块中做了一个重要决策默认让模型自己决定配图方案而不是无脑给每个 section 配一张图。# 文件路径src/modules/image_planning.py import json import re from openai import OpenAI IMAGE_PLAN_PROMPT 根据下面的文章分析结果制定配图计划。 配图计划是一个 JSON 数组每个元素代表一张要生成的图片 [ { position: 图片在文章中的位置可以是段落索引或标题名, description: 这张图片要表达的内容用一句话概括, prompt: 完整的英文提示词用于 Stable Diffusion 生成图片 } ] 要求 1. 不要为每个 section 都配图选信息量最大的 2 到 4 个位置配图。 2. prompt 必须以全局风格描述开头保证风格统一。 3. prompt 要具体描述主体、背景、构图、光影不要只写概念词。 4. 只输出 JSON 数组不要输出其他内容。 全局风格描述 {global_style} 文章分析结果 {analysis_json} def create_image_plan(analysis: dict, article_text: str, style_config: dict, api_key: str, base_url: str, model: str) - list[dict]: if style_config.get(mode) fixed: return _build_fixed_plan(analysis, style_config) client OpenAI(api_keyapi_key, base_urlbase_url) analysis_json json.dumps(analysis, ensure_asciiFalse, indent2) global_style style_config[global_style] prompt IMAGE_PLAN_PROMPT.format( global_styleglobal_style, analysis_jsonanalysis_json, ) response client.chat.completions.create( modelmodel, messages[{role: user, content: prompt}], temperature0.7, ) content response.choices[0].message.content match re.search(r\[.*\], content, re.DOTALL) if not match: raise ValueError(模型未输出有效的配图计划) return json.loads(match.group()) def _build_fixed_plan(analysis: dict, style_config: dict) - list[dict]: 固定数量配图的兜底方案当模型规划失败时使用 global_style style_config[global_style] count style_config.get(fixed_count, 3) sections analysis.get(sections, []) plan [] for i in range(min(count, len(sections))): section sections[i] key_elements section.get(key_elements, []) elements_text , .join(key_elements[:3]) plan.append({ position: section.get(title, fsection-{i}), description: section.get(summary, ), prompt: f{global_style}, {elements_text}, }) return plan_build_fixed_plan是一个很实用的兜底方案。当模型规划因为格式问题返回了不可解析的内容或者你想跳过模型规划直接按固定数量配图时可以用这个函数快速生成计划。5.6 图片生成模块image_generation.py负责和 Stable Diffusion WebUI 通信。Stable Diffusion WebUI 的 txt2img 接口接收 JSON 请求体返回包含图片 base64 的 JSON 响应。我将这个调用封装成单独的生成函数。# 文件路径src/modules/image_generation.py import base64 import requests import time def generate_image(prompt: str, sd_url: str, width: int 768, height: int 512, steps: int 25, cfg_scale: float 7.0, sampler: str DPM 2M Karras, save_path: str None) - str: 调用 Stable Diffusion WebUI API 生成图片 返回 base64 编码的 PNG 图片数据 payload { prompt: prompt, negative_prompt: text, watermark, low quality, blurry, width: width, height: height, steps: steps, cfg_scale: cfg_scale, sampler_name: sampler, batch_size: 1, n_iter: 1, } api_url f{sd_url}/sdapi/v1/txt2img try: response requests.post(api_url, jsonpayload, timeout120) response.raise_for_status() result response.json() if not result.get(images): raise ValueError(生图接口未返回图片数据) image_base64 result[images][0] if save_path: # 去掉 data:image/png;base64, 前缀如果有 if , in image_base64: image_base64 image_base64.split(,, 1)[1] with open(save_path, wb) as f: f.write(base64.b64decode(image_base64)) print(f图片已保存: {save_path}) return image_base64 except requests.exceptions.ConnectionError: raise ConnectionError(f无法连接到 Stable Diffusion WebUI请确认服务已启动: {api_url}) except requests.exceptions.Timeout: raise TimeoutError(生图请求超时请检查显卡性能和网络状态)这段代码里我最看重的是超时和异常处理。生图请求可能很快也可能很慢取决于显卡性能和图片分辨率。timeout120这个值在实际使用中比较合理但如果你的显卡性能较弱建议调到 180 到 300 秒避免花朵因超时而误判失败。5.7 文件读写工具file_utils.py提供读取 Markdown 文件的简单方法后续可以扩展成支持目录批量处理的版本。# 文件路径src/utils/file_utils.py from pathlib import Path def read_markdown_article(path: str) - str: 读取 Markdown 文章内容 file_path Path(path) if not file_path.exists(): raise FileNotFoundError(f文章文件不存在: {path}) return file_path.read_text(encodingutf-8) def save_base64_image(image_base64: str, save_path: str) - None: 将 base64 图片数据保存为文件 import base64 if , in image_base64: image_base64 image_base64.split(,, 1)[1] Path(save_path).parent.mkdir(parentsTrue, exist_okTrue) with open(save_path, wb) as f: f.write(base64.b64decode(image_base64))现在整个最小可用系统已经齐了。配置好.env和config.yaml准备一篇article.md运行python src/main.py就能自动生成配图建议和图片文件。6. 运行结果与效果验证写完代码还要验证整个流程跑得通。我用一篇示例技术文章来测试文章内容是一段关于“云原生架构演进”的简介。测试环境为一台 GPU 服务器显卡为普通的消费级 8GB 显存显卡Stable Diffusion WebUI 以 API 模式启动。运行命令cd article-agent python src/main.py预期输出类似配图完成共生成 3 张图片耗时 45.32 秒同时在项目根目录会生成output.json文件里面包含每张图片的位置、描述、提示词和 base64 图片数据。如果你在generate_image中传了save_path图片也会落盘保存方便直接查看。验证成功与否我建议从三个层面判断第一是流程完整性。日志中是否出现了完整的“文本理解—规划—生成”执行线索是否在合理时间内结束。第二是图文相关性。打开生成的图片对照原始文章段落判断图片是否表达了该段的核心信息。这是最直观的质量验证也是 Agent 配图方案成败的关键。如果图片和文本之间只是弱相关说明提示词生成环节还需要优化。第三是风格一致性。把生成的几张图放一起看确认它们在色调、风格、构图上是统一的。如果风格杂乱第一优先级是检查global_style配置是否生效。如果整个流程运行失败不要着急。先按第 7 节的排查思路检查环境和依赖大多数问题出在服务连接和依赖版本上。我第一次跑通这个流程时就遇到了两个典型问题一是本地 SD WebUI 没有用--api模式启动结果接口一直返回 404二是大模型返回的 JSON 被前后的解释文字包裹正则提取没匹配到导致解析失败。这两个问题都已经在代码里做了兜底处理。7. 常见问题与排查思路在实际运行中自动配图 Agent 比较容易出现以下几类问题。我把它们整理成一张排查表方便你在遇到异常时快速定位。问题现象可能原因排查方式解决方案连接 Stable Diffusion WebUI 失败WebUI 未启动或未加 --api 参数在浏览器访问 http://127.0.0.1:7860 确认服务是否正常以 API 模式重新启动python launch.py --api调用大模型接口报 401 错误API Key 无效或 base_url 配置错误检查 .env 中的 LLM_API_KEY 是否过期确认接口地址格式更新密钥确认 base_url 以 /v1 结尾模型输出 JSON 解析失败提示词约束不够强模型返回了额外文字打印原始响应 content查看前后缀使用更严格的正则提取 JSON或在提示词末尾强调只输出 JSON生成图片与文章风格不一致global_style 未生效或模型规划时忽略了风格前缀查看 output.json 中的 prompt 是否包含风格描述在规划模块中强制把 global_style 拼接到 prompt 开头图片生成速度极慢显卡性能不足或 resolution 设置过高查看显卡显存占用观察 WebUI 日志降低 width/height或减少 steps生成图片内容重复提示词过于抽象模型自由发挥空间大检查 prompt 是否包含具象的元素描述优化 key_elements 生成逻辑尽量给出具象词汇配图位置不准确决策规划模块对文章结构理解不充分查看 analysis 中的 sections 划分是否合理改进文本理解模块的文章分段策略单张图片生成失败导致整个流程卡住重试逻辑缺失异常未捕获查看代码是否捕获了生成模块的异常参考第 5 节在 Agent 编排器中加入重试和跳过逻辑这里我想额外强调一点如果你在 Windows 上运行ConnectionError的一个常见隐藏原因是防火墙拦截了本地端口。可以在第一次启动时暂时关闭防火墙测试如果是这个原因再添加端口放行规则而不是一直改代码。另外Stable Diffusion WebUI 的--api模式一定要确认。很多人部署完 WebUI 之后习惯用网页界面生图忘了加参数结果写好的脚本一请求接口就报 404。这个坑很常见排查优先级排在第一位。8. 工程化实践与生产环境建议跑通最小示例只是第一步。如果要把自动配图 Agent 用在正式的内容生产流程中我认为以下几个工程化问题值得认真对待。8.1 长文章的上下文处理第 5 节代码里用article_text[:6000]做了粗暴截断。这个方案对短视频文案或短文章够用但面对一篇 5000 字以上的深度技术文章直接截断会丢失文章后段的关键信息导致配图计划不完整。如果截断位置正好在代码块中间还可能引入大量无关字符干扰模型理解。更好的方案是采用“分段理解 全局合并”的策略。先把文章按 Markdown 标题拆分成多个 section分别让模型提取要点再让模型基于所有 section 的要点制定统一的配图计划。这样既保住了全局视野又避开了输入长度限制。我在一个内部项目里测试过这种分段策略对长文的配图质量提升非常明显。8.2 提示词版本管理配图 Agent 产生的图片质量高度依赖提示词。而提示词的调整是个不断试错的过程今天把global_style从扁平插画改成 3D 渲染明天给 negative prompt 加一个no text后天发现steps从 25 调到 30 会带来更多细节。这些调整如果不做版本管理会发现图片质量时好时坏很难定位是哪个变量导致的。我的建议是把config.yaml纳入 Git 管理每次调整生成参数时提交一次并在提交信息里记录当时的图片效果。如果条件允许还可以为每次生成记录prompt 参数 结果图片的完整快照这样后续优化有据可查。8.3 安全与权限边界自动配图 Agent 的调用链涉及大模型 API 和本地生图服务两个环节都要注意安全边界。大模型 API 的密钥不能硬编码在代码或打包产物中要通过环境变量或密钥管理服务注入。生图服务如果部署在公网服务器上建议只监听 127.0.0.1不要监听0.0.0.0否则任何人都可以直接调用你的生图接口造成资源被滥用。这个风险常被忽略但实际上非常危险。另外所有请求生产环境的变更都建议先在测试环境验证。比如把配图 Agent 接入 CI/CD 流程话先在一份低风险文档上跑通确认输出符合预期再放开范围。8.4 质量校验的自动化第 5 节实现中的“校验”实际上是靠重试来兜底并没有真正做质量判断。在生产环境中推荐引入轻量级校验生成图片后把原始文本和图片缩略图一起送入多模态大模型让它判断图文是否匹配。不匹配就重新生成。这个过程每张图大概多花几秒和一部分 token但能显著提升配图的靠谱程度避免把明显无关的图插入技术文档。如果对成本敏感也可以用 CLIP 模型计算图文相似度只对相似度低于阈值的图片触发重试。这个方案更高效但对复杂语义的把握不如多模态大模型。8.5 与现有发布流程的衔接自动化配图的最终产出不应该只是散落的图片文件。更合理的做法是让 Agent 在生成图片的同时输出一份带 Markdown 图片语法的插入建议比如告诉你在某个三级标题后面插入。如果配图 Agent 还能直接修改原始 Markdown把图片语法插入到对应位置那就实现了从“配图”到“发布”的完整闭环。不过自动插入有破坏原文的风险建议先输出 diff 由人工确认再正式应用。我自己的实践是让 Agent 生成图片和建议插入位置然后我用一个半自动脚本应用这些建议。这样既保留了自动化带来的高效又保留了人审的关键节点。技术文档发布和代码发布本质上是一样的都需要 review 机制。9. 总结与后续学习方向这一集把 Agent 自动配图的最小可行系统完整讲了一遍。核心思路可以用一句话概括自动配图不是一个“生成图片”的工具而是一个“理解内容 做出规划 执行生成 校验修正”的 Agent 流程。它把内容理解、配图决策、提示词生成、图片生成、质量反馈串成了一个闭环。这个闭环跑通之后你再切换文章主题时根本不用改代码只需要调整config.yaml里的风格和生成参数Agent 就能根据新文章的内容重新制定配图计划。看完这一集你可以先做三件事第一把环境搭起来准备一篇自己的文章跑通第 5 节的完整代码第二仔细观察生成的图片和文章内容的匹配度重点排查不匹配的部分是出在文本理解、规划还是提示词生成阶段第三调整global_style和生成参数找到适合自己文章风格的组合并记录下这些配置。如果你对这一集的内容有疑问或者在实际跑通中遇到了新的问题建议先把报错日志、配置文件和生成结果截图留存再对照第 7 节的排查表一步步定位。Agent 开发本来就是 iterative 的过程第一次失败不代表思路错了很多时候只是某一个小环节的配置没对齐。下一篇内容会继续沿着这个方向深入重点讲如何构建更完善的 Agent 工具链让配图 Agent 能和其他内容生产模块协作。
Agent自动配图：基于大模型的智能图文生成与编排实践
如果有人问我过去一年内容创作领域最值得关注的变化是什么我的答案不是某个大模型版本的升级而是“Agent”这个词从概念炒作变成了真正能落地的生产力工具。尤其在做技术博客、公众号、教程文档这类内容时配图一直是一个让人头疼的环节找图耗时、版权难确认、风格不统一、插图的语义和正文对不上。第5集我们就来专门解决这个问题用 Agent 自动配图把“读文章—想配图—生成图片—插入点位”这条链路全部自动化。先说一个明确判断Agent 自动配图并不是简单“调用一次图片生成 API”而是一个带目标、能拆解、会校验的智能流程。它真正降低的是内容生产中的“视觉编排成本”而不是“点击生成按钮”的那一秒。如果你写过一篇超过 3000 字的技术文章应该能体会写代码只要一小时找一张合适的架构图配图可能要折腾两小时。这中间差的不是工具而是一套能把文本语义翻译成图片提示词的决策机制。这篇文章会沿着一条完整的落地路径展开先从配图痛点讲起说清楚 Agent 在这里承担什么角色然后拆解自动配图的核心原理和系统架构接着给出可运行的代码实现包括环境准备、Agent 主逻辑、图片生成接口调用、质量校验最后是常见问题排查和工程化建议。读完你能跑通一个最小可用的自动配图 Agent并理解怎么把它接入自己的内容生产流程。1. Agent 自动配图到底解决了什么问题配图这件事看着简单真正做起来其实非常琐碎。我自己给技术文章配图时经历过几个阶段最早是去免费图库搜关键词搜出来的图要么风格陈旧要么和文章主题只有弱关联后来尝试截图软件截图遇到流程图、架构图还得自己用画图工具重新画再后来用上了 AI 生图工具输入提示词倒是方便但一个问题随之而来——为文章的十几个段落分别设计并生成风格统一的配图这件事远比想象中耗神。这里的核心矛盾是一篇文章是一个整体图片之间要有视觉一致性图片与文本之间要有语义对齐。而人工操作时这种一致性完全依赖配图者的经验。今天用插画风明天用 3D 渲染风后天换成线条图读者一眼就能看出不是一套图。Agent 自动配图解决的不只是“省时间”而是把配图从“自由发挥”变成了“有流程可循的工程任务”。Agent 会先阅读全文理解每部分的主题和情绪然后统一制定视觉风格和配图数量再逐段生成提示词并调用生图模型最后对生成结果做校验。整个过程里Agent 像一个熟悉你写作习惯的视觉编辑而不是一个只会听指令的绘图机器。这也回答了另一个很实际的问题自动配图适合谁如果你运营技术博客、写课程讲义、做企业知识库、维护开源项目文档或者经常需要把技术方案整理成图文报告Agent 自动配图都值得做一套。反过来如果你只是偶尔发一条朋友圈配图那确实用不上这么重的流程直接用现成的 AI 生图工具或者图库就够了。判断一个自动化方案值不值得做不应该只看“操作时间少了多少”还要看“质量的一致性和可复用性”。Agent 配图方案的价值恰恰在后两点一次写好的配图流程可以反复用在后续所有文章中而且产出的图片风格由同一套提示词策略保证质量下限会明显高于人工随意发挥。2. Agent 配图的核心原理与工作流程想理解 Agent 自动配图首先要跳出“一个函数调用到底”的惯性思维。传统编程里我们要给程序明确每一步指令先读取文本再分割章节硬编码生成提示词最后调图片接口。这套写法的问题在于不同文章的结构千差万别硬编码规则无法适应“这篇是教程那篇是产品发布”的差异。Agent 的做法不一样。它把大模型当作一个“可以自主思考的执行体”我们只给它目标和方法它自己决定怎么行动。这里用到的经典模式是 ReAct也就是 Reasoning Acting。Agent 在一个循环里交替进行“思考—行动—观察”思考根据当前输入决定下一步该做什么。行动调用某个工具比如读取文章、生成提示词、调用生图 API。观察查看工具返回的结果判断是否达到预期目标。如果没有达到目标Agent 就进入下一轮思考调整策略再试。这正是自动配图和普通脚本的本质区别普通脚本出错就停Agent 出错会自我修正。放到自动配图场景一个标准的工作流程包含五个阶段。第一阶段是内容理解。Agent 把整篇文章文本送入大模型提炼出文章主题、各个段落的子主题、文章的语调和风格。这一步的输出是一份“文章结构化摘要”。第二阶段是配图规划。Agent 根据摘要决定配几张图、每张图放在什么位置、每张图要表达什么信息。这里要考虑文章长度和内容的丰富程度。注意配图数量不是越多越好规划的关键是“每张图都有信息增量”。第三阶段是提示词生成。Agent 为每张目标图片编写生图模型能理解的英文提示词同时为了保持风格统一会在一开始就定义一个全局风格标签比如“Tech illustration, flat design, blue color palette”之后每张图的提示词都包含这个风格前缀。第四阶段是图片生成。Agent 调用部署在本地的 Stable Diffusion WebUI API或者云端生图服务将提示词转换成图片。第五阶段是结果校验。Agent 把生成的图片和原始文本一起“理解”一遍判断图片是否贴合语义或者利用 CLIP 这类模型计算图文相关度。如果相关度不够Agent 会调整提示词重新生成。这五个阶段不是一次性能完成的。我在实际实现中倾向于把 Agent 设计成“规划—执行—反思”的三层循环外层负责配图计划内层负责单张图片的生成与重试。理解这个流程后再去看代码就不会被循环调用绕晕。3. 自动配图系统的整体架构设计明确了工作流程接下来要把流程落地成代码架构。一个生产环境可用的自动配图 Agent 至少包含四个模块文本理解模块、决策规划模块、图片生成模块、质量校验模块。再加上一个编排器也就是 Agent 的核心执行引擎。文本理解模块的职责是调用大模型 API把长文本处理成结构化的 JSON 输出。这个模块要处理的关键问题是输入长度。一篇文章可能有三五千字直接塞给模型做理解不是不行但为了控制成本和提升响应速度通常会先做分段处理再逐段提取要点。决策规划模块是整个系统的“大脑”。它接收文本理解的输出结合用户配置的偏好输出配图计划包括图片数量、图中元素、图片风格、插入位置。这个模块决定了整篇文章的配图节奏判断哪一段需要详细图示哪一段可以用简单的装饰图带过。图片生成模块是执行层。我选择对接 Stable Diffusion WebUI 的 API因为它开源、可本地部署而且没有内容合规风险。Stable Diffusion WebUI 启动后会监听一个本地端口只要向这个端口发送 txt2img 请求就能返回生成图片的 base64 数据。质量校验模块容易被忽略但却是保证“自动配图质量下限”的关键。它可以用两种策略一是让大模型根据生成的图片和对应文本来回判断二是调用 CLIP 模型计算图文向量的余弦相似度。前者的优点是理解能力强缺点是多一次大模型调用后者的优点是快缺点是对抽象概念的判断不够准。建议在小成本场景先用大模型校验高频生产场景再引入 CLIP。模块之间通过数据对象通信我定义了几种关键的数据结构ArticleAnalysis表示文章分析结果ImagePlan表示配图计划ImageResult表示单张生成结果。这样解耦的好处是每一步都可以单独调试也可以替换成其他实现比如把 Stable Diffusion WebUI 换成云端生图服务只需要改图片生成模块。整个系统的交互流程可以概括为主程序读入 Markdown 文章交给 Agent 编排器编排器调用文本理解模块得到结构化分析决策规划模块产出配图计划编排器遍历计划逐张调用图片生成模块中途出现失败或校验不通过就触发重试全部完成后返回图片列表和插入建议。接下来我们进入实操。我会用一个完整示例演示这套架构示例基于 Python 实现大模型部分使用 OpenAI SDK 兼容的通用接口生图部分对接本地 Stable Diffusion WebUI。4. 环境准备与依赖安装在动手写代码之前先把运行环境准备好。以下是推荐的环境配置版本以实际安装为准本文重点演示通用思路不绑定某个具体版本。操作系统方面建议 Linux 或 macOSWindows 也可以跑但 Stabel Diffusion WebUI 的本地部署在 Windows 上需要额外注意显卡驱动和路径问题。Python 版本要求 3.9 以上推荐 3.10 或 3.11太新的 Python 版本有时会遇到个别依赖库尚未适配的情况。依赖安装使用 pip。创建一个虚拟环境然后安装以下核心库python -m venv .venv source .venv/bin/activate pip install openai pip install requests pip install python-dotenv pip install pyyaml说明一下每个库的用途openai官方 Python SDK用来调用大模型 API支持通过 base_url 切换兼容服务。requests用来调用 Stable Diffusion WebUI 的 HTTP 接口。python-dotenv用来读取 .env 文件中的密钥配置。pyyaml用来解析配置文件比如文章路径、风格设定、生成参数。大模型的选择上建议用一个上下文长度足够、指令跟随能力强、成本适中的模型。文本理解和提示词生成属于中等难度任务不需要用最强的模型但也不要用能力太弱的模型否则规划阶段会频繁出现逻辑混乱。生图模型的部署有两种方式。第一种是本地部署 Stable Diffusion WebUI优点是免费、可扩展、隐私可控缺点是依赖 GPU生成速度看显卡性能第二种是调用已部署好的云服务优点是省事缺点是要花钱而且每次请求都要经过网络传输生成大图时有等待成本。如果你选择本地部署 Stable Diffusion WebUI安装完成后需要以 API 模式启动python launch.py --api启动成功的标志是终端输出Running on local URL: http://127.0.0.1:7860。后续示例代码会向这个地址的/sdapi/v1/txt2img接口发送 POST 请求。最后在项目根目录创建一个.env文件填入大模型 API 配置LLM_API_KEYsk-your-key-here LLM_BASE_URLhttps://your-endpoint.example.com/v1 LLM_MODELgpt-4o-mini SD_URLhttp://127.0.0.1:7860注意不要把这文件提交到 Git 仓库。.gitignore里务必加上.env。5. 核心代码实现一个最小可用配图 Agent现在开始写代码。我会按照模块化的方式组织最终形成一个可以直接运行的命令行工具。完整项目结构如下article-agent/ ├── .env ├── requirements.txt ├── config.yaml ├── article.md └── src/ ├── __init__.py ├── main.py ├── agent.py ├── modules/ │ ├── __init__.py │ ├── text_understanding.py │ ├── image_planning.py │ └── image_generation.py └── utils/ ├── __init__.py └── file_utils.py先从最外层的主入口开始理解整体调用关系再逐步看每个模块的实现。5.1 主入口与配置加载main.py负责加载配置、读取文章、调用 Agent并把结果输出为一份配图建议 JSON。为了让流程更清晰我把配置项统一放到config.yaml里和代码分离。# 文件路径src/main.py import os import json import time from dotenv import load_dotenv import yaml from agent import AutoImageAgent from utils.file_utils import read_markdown_article # 加载 .env 文件中的环境变量 load_dotenv() def load_config(config_path: str) - dict: 加载 YAML 配置文件 with open(config_path, r, encodingutf-8) as f: return yaml.safe_load(f) def main(): config_path os.path.join(os.path.dirname(__file__), .., config.yaml) config load_config(config_path) article_path config[article][path] style_config config[style] generation_config config[generation] # 读取要配图的 Markdown 文章 article_text read_markdown_article(article_path) # 初始化 Agent agent AutoImageAgent( llm_api_keyos.getenv(LLM_API_KEY), llm_base_urlos.getenv(LLM_BASE_URL), llm_modelos.getenv(LLM_MODEL), sd_urlos.getenv(SD_URL), style_configstyle_config, generation_configgeneration_config, ) # 执行自动配图流程 start time.time() result agent.run(article_text) elapsed time.time() - start # 输出结果 output { elapsed_seconds: round(elapsed, 2), image_count: len(result[images]), images: result[images], } output_path os.path.join(os.path.dirname(__file__), .., output.json) with open(output_path, w, encodingutf-8) as f: json.dump(output, f, ensure_asciiFalse, indent2) print(f配图完成共生成 {len(result[images])} 张图片耗时 {elapsed:.2f} 秒) if __name__ __main__: main()这段代码本身没有复杂的逻辑它只负责串联。真正的 Agent 行为在agent.py中定义。5.2 配置示例config.yaml的内容如下它集中控制了配图风格和生成参数是调整 Agent 行为的“操作面板”。# 文件路径config.yaml article: path: ./article.md style: # 全局视觉风格描述会拼接到每张图片的提示词前 global_style: Tech illustration, flat design, soft blue gradient background, high contrast, clean composition # 配图模式auto 表示由模型决策fixed 表示固定数量 mode: auto # 当 mode 为 fixed 时生效 fixed_count: 3 generation: width: 768 height: 512 steps: 25 cfg_scale: 7.0 sampler: DPM 2M Karras # 每张图片最大重试次数 max_retries: 2这里的global_style是保持整套配图风格统一的关键。如果不设置这个值模型很可能会给不同段落生成风格差异很大的图片。generation下的参数会被直接透传给生图接口。5.3 Agent 编排器AutoImageAgent类是整套系统的大脑。它把前面说的四个模块串起来实现“分析—规划—生成—校验—重试”的完整循环。为了让逻辑更清晰我没有把校验单独拆成一个类而是把它合并在 Agent 的生成流程里。# 文件路径src/agent.py import re from modules.text_understanding import understand_article from modules.image_planning import create_image_plan from modules.image_generation import generate_image class AutoImageAgent: 自动配图 Agent负责全流程编排 def __init__(self, llm_api_key, llm_base_url, llm_model, sd_url, style_config, generation_config): self.llm_api_key llm_api_key self.llm_base_url llm_base_url self.llm_model llm_model self.sd_url sd_url self.style_config style_config self.generation_config generation_config def run(self, article_text: str) - dict: # 第1步理解文章 analysis understand_article( article_textarticle_text, api_keyself.llm_api_key, base_urlself.llm_base_url, modelself.llm_model, ) # 第2步制定配图计划 plan create_image_plan( analysisanalysis, article_textarticle_text, style_configself.style_config, api_keyself.llm_api_key, base_urlself.llm_base_url, modelself.llm_model, ) # 第3步逐张生成图片失败自动重试 images [] for item in plan: image_info self._generate_with_retry(item) if image_info is not None: images.append(image_info) return {analysis: analysis, images: images, plan: plan} def _generate_with_retry(self, item: dict) - dict | None: 单张图片生成带重试机制 prompt item[prompt] desc item[description] position item[position] max_retries self.generation_config.get(max_retries, 2) for attempt in range(max_retries 1): try: image_data generate_image( promptprompt, sd_urlself.sd_url, widthself.generation_config[width], heightself.generation_config[height], stepsself.generation_config[steps], cfg_scaleself.generation_config[cfg_scale], samplerself.generation_config[sampler], ) return { position: position, description: desc, prompt: prompt, image_base64: image_data, } except Exception as e: print(f第 {attempt 1} 次生成失败: {e}) if attempt max_retries: # 简单策略给提示词追加 more detail 后重试 prompt prompt , more details, better composition else: print(f图片 {position} 生成失败已跳过) return None这里有一个容易踩坑的地方_generate_with_retry中的重试不能无脑执行否则接口如果持续报错整个流程会被拖很长时间。所以我用max_retries控制重试上限超过上限就跳过当前图片继续处理下一张保证整个配图流程不会因为单张图片失败而中断。这个设计在生产环境里很重要。5.4 文本理解模块text_understanding.py负责把文章正文转换成结构化分析结果。实现的思路是让大模型输出 JSON然后用正则从返回内容中提取 JSON 片段。这样做的好处是即使模型偶尔输出了一些前缀解释文字也能容错解析。# 文件路径src/modules/text_understanding.py import json import re from openai import OpenAI ARTICLE_ANALYSIS_PROMPT 你是一名资深的内容编辑。请阅读下面的文章然后输出 JSON 格式的分析结果。 JSON 必须包含以下字段 { topic: 文章的核心主题, tone: 文章的语调和风格, sections: [ { title: 段落或小节的标题, summary: 这一段的核心内容概述, key_elements: [这一段可以配图的关键元素数组每个元素用英文短句描述] } ] } 注意 1. sections 数量控制在 3 到 6 个。 2. key_elements 里的描述要具体不要写 technology 这种抽象词要写 a laptop with code on screen 这样的具象描述。 3. 只输出 JSON不要输出其他解释。 文章内容如下 {article_text} def understand_article(article_text: str, api_key: str, base_url: str, model: str) - dict: client OpenAI(api_keyapi_key, base_urlbase_url) prompt ARTICLE_ANALYSIS_PROMPT.format(article_textarticle_text[:6000]) response client.chat.completions.create( modelmodel, messages[{role: user, content: prompt}], temperature0.3, ) content response.choices[0].message.content # 提取 JSON 片段 match re.search(r\{.*\}, content, re.DOTALL) if not match: raise ValueError(模型输出未包含有效 JSON) return json.loads(match.group())注意article_text[:6000]这个截断操作是临时的简化处理。如果文章很长更好的做法是把文章按标题拆分成多个片段分别分析再合并结果。后面第 8 节我会展开讲优化思路。5.5 配图规划模块image_planning.py生成具体的配图计划。它会基于文本理解的结果结合用户配置的风格信息为每个 section 决定是否配图以及配什么样的图。我在这个模块中做了一个重要决策默认让模型自己决定配图方案而不是无脑给每个 section 配一张图。# 文件路径src/modules/image_planning.py import json import re from openai import OpenAI IMAGE_PLAN_PROMPT 根据下面的文章分析结果制定配图计划。 配图计划是一个 JSON 数组每个元素代表一张要生成的图片 [ { position: 图片在文章中的位置可以是段落索引或标题名, description: 这张图片要表达的内容用一句话概括, prompt: 完整的英文提示词用于 Stable Diffusion 生成图片 } ] 要求 1. 不要为每个 section 都配图选信息量最大的 2 到 4 个位置配图。 2. prompt 必须以全局风格描述开头保证风格统一。 3. prompt 要具体描述主体、背景、构图、光影不要只写概念词。 4. 只输出 JSON 数组不要输出其他内容。 全局风格描述 {global_style} 文章分析结果 {analysis_json} def create_image_plan(analysis: dict, article_text: str, style_config: dict, api_key: str, base_url: str, model: str) - list[dict]: if style_config.get(mode) fixed: return _build_fixed_plan(analysis, style_config) client OpenAI(api_keyapi_key, base_urlbase_url) analysis_json json.dumps(analysis, ensure_asciiFalse, indent2) global_style style_config[global_style] prompt IMAGE_PLAN_PROMPT.format( global_styleglobal_style, analysis_jsonanalysis_json, ) response client.chat.completions.create( modelmodel, messages[{role: user, content: prompt}], temperature0.7, ) content response.choices[0].message.content match re.search(r\[.*\], content, re.DOTALL) if not match: raise ValueError(模型未输出有效的配图计划) return json.loads(match.group()) def _build_fixed_plan(analysis: dict, style_config: dict) - list[dict]: 固定数量配图的兜底方案当模型规划失败时使用 global_style style_config[global_style] count style_config.get(fixed_count, 3) sections analysis.get(sections, []) plan [] for i in range(min(count, len(sections))): section sections[i] key_elements section.get(key_elements, []) elements_text , .join(key_elements[:3]) plan.append({ position: section.get(title, fsection-{i}), description: section.get(summary, ), prompt: f{global_style}, {elements_text}, }) return plan_build_fixed_plan是一个很实用的兜底方案。当模型规划因为格式问题返回了不可解析的内容或者你想跳过模型规划直接按固定数量配图时可以用这个函数快速生成计划。5.6 图片生成模块image_generation.py负责和 Stable Diffusion WebUI 通信。Stable Diffusion WebUI 的 txt2img 接口接收 JSON 请求体返回包含图片 base64 的 JSON 响应。我将这个调用封装成单独的生成函数。# 文件路径src/modules/image_generation.py import base64 import requests import time def generate_image(prompt: str, sd_url: str, width: int 768, height: int 512, steps: int 25, cfg_scale: float 7.0, sampler: str DPM 2M Karras, save_path: str None) - str: 调用 Stable Diffusion WebUI API 生成图片 返回 base64 编码的 PNG 图片数据 payload { prompt: prompt, negative_prompt: text, watermark, low quality, blurry, width: width, height: height, steps: steps, cfg_scale: cfg_scale, sampler_name: sampler, batch_size: 1, n_iter: 1, } api_url f{sd_url}/sdapi/v1/txt2img try: response requests.post(api_url, jsonpayload, timeout120) response.raise_for_status() result response.json() if not result.get(images): raise ValueError(生图接口未返回图片数据) image_base64 result[images][0] if save_path: # 去掉 data:image/png;base64, 前缀如果有 if , in image_base64: image_base64 image_base64.split(,, 1)[1] with open(save_path, wb) as f: f.write(base64.b64decode(image_base64)) print(f图片已保存: {save_path}) return image_base64 except requests.exceptions.ConnectionError: raise ConnectionError(f无法连接到 Stable Diffusion WebUI请确认服务已启动: {api_url}) except requests.exceptions.Timeout: raise TimeoutError(生图请求超时请检查显卡性能和网络状态)这段代码里我最看重的是超时和异常处理。生图请求可能很快也可能很慢取决于显卡性能和图片分辨率。timeout120这个值在实际使用中比较合理但如果你的显卡性能较弱建议调到 180 到 300 秒避免花朵因超时而误判失败。5.7 文件读写工具file_utils.py提供读取 Markdown 文件的简单方法后续可以扩展成支持目录批量处理的版本。# 文件路径src/utils/file_utils.py from pathlib import Path def read_markdown_article(path: str) - str: 读取 Markdown 文章内容 file_path Path(path) if not file_path.exists(): raise FileNotFoundError(f文章文件不存在: {path}) return file_path.read_text(encodingutf-8) def save_base64_image(image_base64: str, save_path: str) - None: 将 base64 图片数据保存为文件 import base64 if , in image_base64: image_base64 image_base64.split(,, 1)[1] Path(save_path).parent.mkdir(parentsTrue, exist_okTrue) with open(save_path, wb) as f: f.write(base64.b64decode(image_base64))现在整个最小可用系统已经齐了。配置好.env和config.yaml准备一篇article.md运行python src/main.py就能自动生成配图建议和图片文件。6. 运行结果与效果验证写完代码还要验证整个流程跑得通。我用一篇示例技术文章来测试文章内容是一段关于“云原生架构演进”的简介。测试环境为一台 GPU 服务器显卡为普通的消费级 8GB 显存显卡Stable Diffusion WebUI 以 API 模式启动。运行命令cd article-agent python src/main.py预期输出类似配图完成共生成 3 张图片耗时 45.32 秒同时在项目根目录会生成output.json文件里面包含每张图片的位置、描述、提示词和 base64 图片数据。如果你在generate_image中传了save_path图片也会落盘保存方便直接查看。验证成功与否我建议从三个层面判断第一是流程完整性。日志中是否出现了完整的“文本理解—规划—生成”执行线索是否在合理时间内结束。第二是图文相关性。打开生成的图片对照原始文章段落判断图片是否表达了该段的核心信息。这是最直观的质量验证也是 Agent 配图方案成败的关键。如果图片和文本之间只是弱相关说明提示词生成环节还需要优化。第三是风格一致性。把生成的几张图放一起看确认它们在色调、风格、构图上是统一的。如果风格杂乱第一优先级是检查global_style配置是否生效。如果整个流程运行失败不要着急。先按第 7 节的排查思路检查环境和依赖大多数问题出在服务连接和依赖版本上。我第一次跑通这个流程时就遇到了两个典型问题一是本地 SD WebUI 没有用--api模式启动结果接口一直返回 404二是大模型返回的 JSON 被前后的解释文字包裹正则提取没匹配到导致解析失败。这两个问题都已经在代码里做了兜底处理。7. 常见问题与排查思路在实际运行中自动配图 Agent 比较容易出现以下几类问题。我把它们整理成一张排查表方便你在遇到异常时快速定位。问题现象可能原因排查方式解决方案连接 Stable Diffusion WebUI 失败WebUI 未启动或未加 --api 参数在浏览器访问 http://127.0.0.1:7860 确认服务是否正常以 API 模式重新启动python launch.py --api调用大模型接口报 401 错误API Key 无效或 base_url 配置错误检查 .env 中的 LLM_API_KEY 是否过期确认接口地址格式更新密钥确认 base_url 以 /v1 结尾模型输出 JSON 解析失败提示词约束不够强模型返回了额外文字打印原始响应 content查看前后缀使用更严格的正则提取 JSON或在提示词末尾强调只输出 JSON生成图片与文章风格不一致global_style 未生效或模型规划时忽略了风格前缀查看 output.json 中的 prompt 是否包含风格描述在规划模块中强制把 global_style 拼接到 prompt 开头图片生成速度极慢显卡性能不足或 resolution 设置过高查看显卡显存占用观察 WebUI 日志降低 width/height或减少 steps生成图片内容重复提示词过于抽象模型自由发挥空间大检查 prompt 是否包含具象的元素描述优化 key_elements 生成逻辑尽量给出具象词汇配图位置不准确决策规划模块对文章结构理解不充分查看 analysis 中的 sections 划分是否合理改进文本理解模块的文章分段策略单张图片生成失败导致整个流程卡住重试逻辑缺失异常未捕获查看代码是否捕获了生成模块的异常参考第 5 节在 Agent 编排器中加入重试和跳过逻辑这里我想额外强调一点如果你在 Windows 上运行ConnectionError的一个常见隐藏原因是防火墙拦截了本地端口。可以在第一次启动时暂时关闭防火墙测试如果是这个原因再添加端口放行规则而不是一直改代码。另外Stable Diffusion WebUI 的--api模式一定要确认。很多人部署完 WebUI 之后习惯用网页界面生图忘了加参数结果写好的脚本一请求接口就报 404。这个坑很常见排查优先级排在第一位。8. 工程化实践与生产环境建议跑通最小示例只是第一步。如果要把自动配图 Agent 用在正式的内容生产流程中我认为以下几个工程化问题值得认真对待。8.1 长文章的上下文处理第 5 节代码里用article_text[:6000]做了粗暴截断。这个方案对短视频文案或短文章够用但面对一篇 5000 字以上的深度技术文章直接截断会丢失文章后段的关键信息导致配图计划不完整。如果截断位置正好在代码块中间还可能引入大量无关字符干扰模型理解。更好的方案是采用“分段理解 全局合并”的策略。先把文章按 Markdown 标题拆分成多个 section分别让模型提取要点再让模型基于所有 section 的要点制定统一的配图计划。这样既保住了全局视野又避开了输入长度限制。我在一个内部项目里测试过这种分段策略对长文的配图质量提升非常明显。8.2 提示词版本管理配图 Agent 产生的图片质量高度依赖提示词。而提示词的调整是个不断试错的过程今天把global_style从扁平插画改成 3D 渲染明天给 negative prompt 加一个no text后天发现steps从 25 调到 30 会带来更多细节。这些调整如果不做版本管理会发现图片质量时好时坏很难定位是哪个变量导致的。我的建议是把config.yaml纳入 Git 管理每次调整生成参数时提交一次并在提交信息里记录当时的图片效果。如果条件允许还可以为每次生成记录prompt 参数 结果图片的完整快照这样后续优化有据可查。8.3 安全与权限边界自动配图 Agent 的调用链涉及大模型 API 和本地生图服务两个环节都要注意安全边界。大模型 API 的密钥不能硬编码在代码或打包产物中要通过环境变量或密钥管理服务注入。生图服务如果部署在公网服务器上建议只监听 127.0.0.1不要监听0.0.0.0否则任何人都可以直接调用你的生图接口造成资源被滥用。这个风险常被忽略但实际上非常危险。另外所有请求生产环境的变更都建议先在测试环境验证。比如把配图 Agent 接入 CI/CD 流程话先在一份低风险文档上跑通确认输出符合预期再放开范围。8.4 质量校验的自动化第 5 节实现中的“校验”实际上是靠重试来兜底并没有真正做质量判断。在生产环境中推荐引入轻量级校验生成图片后把原始文本和图片缩略图一起送入多模态大模型让它判断图文是否匹配。不匹配就重新生成。这个过程每张图大概多花几秒和一部分 token但能显著提升配图的靠谱程度避免把明显无关的图插入技术文档。如果对成本敏感也可以用 CLIP 模型计算图文相似度只对相似度低于阈值的图片触发重试。这个方案更高效但对复杂语义的把握不如多模态大模型。8.5 与现有发布流程的衔接自动化配图的最终产出不应该只是散落的图片文件。更合理的做法是让 Agent 在生成图片的同时输出一份带 Markdown 图片语法的插入建议比如告诉你在某个三级标题后面插入。如果配图 Agent 还能直接修改原始 Markdown把图片语法插入到对应位置那就实现了从“配图”到“发布”的完整闭环。不过自动插入有破坏原文的风险建议先输出 diff 由人工确认再正式应用。我自己的实践是让 Agent 生成图片和建议插入位置然后我用一个半自动脚本应用这些建议。这样既保留了自动化带来的高效又保留了人审的关键节点。技术文档发布和代码发布本质上是一样的都需要 review 机制。9. 总结与后续学习方向这一集把 Agent 自动配图的最小可行系统完整讲了一遍。核心思路可以用一句话概括自动配图不是一个“生成图片”的工具而是一个“理解内容 做出规划 执行生成 校验修正”的 Agent 流程。它把内容理解、配图决策、提示词生成、图片生成、质量反馈串成了一个闭环。这个闭环跑通之后你再切换文章主题时根本不用改代码只需要调整config.yaml里的风格和生成参数Agent 就能根据新文章的内容重新制定配图计划。看完这一集你可以先做三件事第一把环境搭起来准备一篇自己的文章跑通第 5 节的完整代码第二仔细观察生成的图片和文章内容的匹配度重点排查不匹配的部分是出在文本理解、规划还是提示词生成阶段第三调整global_style和生成参数找到适合自己文章风格的组合并记录下这些配置。如果你对这一集的内容有疑问或者在实际跑通中遇到了新的问题建议先把报错日志、配置文件和生成结果截图留存再对照第 7 节的排查表一步步定位。Agent 开发本来就是 iterative 的过程第一次失败不代表思路错了很多时候只是某一个小环节的配置没对齐。下一篇内容会继续沿着这个方向深入重点讲如何构建更完善的 Agent 工具链让配图 Agent 能和其他内容生产模块协作。
