你寫(xiě)完一篇技術(shù)文章最終想讓讀者能做什么答案是讓讀者把“配圖”這個(gè)經(jīng)常被當(dāng)作靈感的活兒壓縮成一條可重復(fù)執(zhí)行的個(gè)人工作流。人工找圖、裁剪、統(tǒng)一風(fēng)格很費(fèi)時(shí)間而大模型配合工具調(diào)用能夠把“閱讀理解文章結(jié)構(gòu) → 生成配圖計(jì)劃 → 調(diào)用工具取圖 → 校驗(yàn)圖片 → 插入Markdown”這一套動(dòng)作自動(dòng)化。這篇文章就以“第5集-Agent自動(dòng)配圖”為切入點(diǎn)講清楚Agent做自動(dòng)配圖的核心機(jī)制、完整代碼實(shí)現(xiàn)、運(yùn)行驗(yàn)證和最容易踩的坑。關(guān)于Agent自動(dòng)配圖我的核心判斷是它真正的價(jià)值不是“生成一張好看的圖”而是“把配圖決策流程穩(wěn)定地復(fù)制下來(lái)”。傳統(tǒng)腳本只能按規(guī)則硬匹配規(guī)則越多越脆弱Agent方案則把“規(guī)劃”交給大模型把“執(zhí)行”交給工具把“兜底”交給代碼校驗(yàn)。所以它適合內(nèi)容平臺(tái)批量創(chuàng)作、知識(shí)庫(kù)富文本化、PPT/課程配圖等場(chǎng)景而不適合需要極度精確、品牌一致性要求極高的商業(yè)設(shè)計(jì)。文章會(huì)從問(wèn)題出發(fā)解釋Agent自動(dòng)配圖的基本概念再做方案選型然后給出一套可直接運(yùn)行的Python示例覆蓋環(huán)境準(zhǔn)備、核心代碼、運(yùn)行驗(yàn)證、常見(jiàn)問(wèn)題排查和工程建議。讀完你能自己搭一套“標(biāo)題/文章 → Markdown配圖文稿”的自動(dòng)化管線(xiàn)也明白后續(xù)往Multi-Agent、記憶、Skills方向擴(kuò)展時(shí)該怎么下手。1. 這篇文章真正要解決的問(wèn)題先聊一個(gè)非常實(shí)際的場(chǎng)景。很多做技術(shù)博客、公眾號(hào)排版、課程PPT的人每個(gè)星期都要處理大量配圖需求一篇3000字的文章可能需要4到6張配圖每一張都要符合段落語(yǔ)義、風(fēng)格統(tǒng)一、版權(quán)安全。傳統(tǒng)做法是打開(kāi)圖庫(kù)網(wǎng)站反復(fù)搜索、篩選、下載再手動(dòng)改尺寸、重命名、上傳圖床最后回到Markdown編輯器里一張張插入。這個(gè)過(guò)程非常反鎖尤其當(dāng)你有幾十篇文章待發(fā)布時(shí)它消耗的時(shí)間和注意力遠(yuǎn)超你的預(yù)期。更麻煩的是配圖本身帶有判斷邏輯第一張圖應(yīng)該強(qiáng)調(diào)核心概念中間章節(jié)需要展示流程或?qū)Ρ冉Y(jié)尾通常是總結(jié)性視覺(jué)。這些判斷聽(tīng)起來(lái)簡(jiǎn)單但不同人執(zhí)行結(jié)果會(huì)差很多。而“判斷執(zhí)行”的組合恰恰是Agent擅長(zhǎng)的事情。Agent自動(dòng)配圖簡(jiǎn)單來(lái)說(shuō)就是讓大語(yǔ)言模型扮演“圖片編輯規(guī)劃師”先讀文章再?zèng)Q定每段配什么圖、用什么風(fēng)格、從哪里取圖然后把取圖和生成圖的操作交給可執(zhí)行的工具函數(shù)。整個(gè)流程從“人工找圖手工插入”變成“輸入文章 → 輸出帶配圖的Markdown”執(zhí)行速度和一致性都大幅提升。這篇文章適合三類(lèi)讀者需要批量生產(chǎn)內(nèi)容的技術(shù)作者希望減少排版環(huán)節(jié)的重復(fù)勞動(dòng)。正在學(xué)習(xí)Agent開(kāi)發(fā)想找一個(gè)完整可落地案例的新手。已經(jīng)在用LangChain或其他Agent框架但不知道如何把“工具調(diào)用”和“內(nèi)容創(chuàng)作”結(jié)合起來(lái)的開(kāi)發(fā)者。如果你只是偶爾給一篇隨筆配圖用在線(xiàn)圖庫(kù)手動(dòng)選也夠用。但如果你想從“靠感覺(jué)”變成“靠流程”或者想把這個(gè)能力沉淀成團(tuán)隊(duì)工具那么Agent自動(dòng)配圖值得認(rèn)真搭一次。2. Agent自動(dòng)配圖的核心概念與工作原理在深入代碼之前先建立幾個(gè)概念。這里講的Agent不是一個(gè)玄學(xué)概念它的本質(zhì)可以拆成三層規(guī)劃層大模型接收輸入文本根據(jù)任務(wù)目標(biāo)生成步驟序列。例如“文章分為5段需要在第2段后放一張對(duì)比圖在第4段后放一張架構(gòu)圖”。工具層一組預(yù)定義好的函數(shù)比如search_image表示搜索圖庫(kù)generate_image表示調(diào)用圖像生成模型。Agent通過(guò)函數(shù)調(diào)用機(jī)制選擇并執(zhí)行這些函數(shù)。反饋層工具執(zhí)行后會(huì)返回結(jié)果Agent讀取結(jié)果決定繼續(xù)或終止。例如搜圖失敗時(shí)Agent可以改用生成圖的方式兜底。在自動(dòng)配圖場(chǎng)景里Agent的輸入是一篇文章或一個(gè)標(biāo)題輸出是“配圖計(jì)劃 圖片文件 插入位置”。它不是一個(gè)單獨(dú)的大模型調(diào)用而是多次調(diào)用、多次工具執(zhí)行、多次校驗(yàn)的循環(huán)過(guò)程。關(guān)于Agent開(kāi)發(fā)經(jīng)常被混淆的一個(gè)點(diǎn)是“Agent框架和Skill到底怎么理解”。簡(jiǎn)單說(shuō)框架解決的是“Agent怎么規(guī)劃、怎么調(diào)用工具、怎么維護(hù)上下文”相當(dāng)于骨架Skill則是把一組專(zhuān)門(mén)能力打包比如“圖片版權(quán)審核”是一個(gè)Skill“圖片風(fēng)格統(tǒng)一”是另一個(gè)Skill。在你的項(xiàng)目早期不需要把Skill做得特別復(fù)雜先把工具調(diào)用跑通更重要。另一個(gè)常見(jiàn)誤區(qū)是“Agent就是提示詞模板”。提示詞模板只能按固定順序生成文本但真正的Agent需要能夠根據(jù)中間結(jié)果動(dòng)態(tài)調(diào)整下一步。比如初始方案是搜圖搜不到時(shí)改為生成這個(gè)分支能力才是Agent和腳本的分水嶺。自動(dòng)配圖Agent的典型執(zhí)行流程如下Agent讀取整篇Markdown文章。按段落拆分配圖點(diǎn)生成配圖計(jì)劃計(jì)劃中包含位置、主題、風(fēng)格、比例。對(duì)計(jì)劃中的每一項(xiàng)優(yōu)先調(diào)用搜索工具從圖庫(kù)中取候選圖。如果取圖失敗或者用戶(hù)配置為“全部生成”則調(diào)用圖像生成工具。下載圖片到本地或圖床統(tǒng)一重命名。在原文中插入圖片引用生成新的Markdown文件。匯總報(bào)告列出每張圖的來(lái)源和可能存在的版權(quán)提示。從這一流程能看出自動(dòng)配圖Agent不是“模型畫(huà)畫(huà)給你看”而是“模型做決策 工具做執(zhí)行 代碼做保障”。3. 方案選型自研腳本、LangChain Agent還是自建Agent實(shí)現(xiàn)自動(dòng)配圖眼前有三條路線(xiàn)需要先做一個(gè)明確選型。3.1 傳統(tǒng)規(guī)則腳本思路是人工定義關(guān)鍵詞詞庫(kù)例如出現(xiàn)“數(shù)據(jù)庫(kù)”就配數(shù)據(jù)庫(kù)圖片出現(xiàn)“云原生”就配云原生圖片。優(yōu)點(diǎn)是沒(méi)有大模型成本執(zhí)行速度快缺點(diǎn)是詞庫(kù)維護(hù)成本高遇到語(yǔ)義復(fù)雜的長(zhǎng)文時(shí)匹配質(zhì)量很差。比如文章寫(xiě)“我用三天把數(shù)據(jù)從A遷移到B”規(guī)則腳本可能抓不到“遷移”這個(gè)核心意圖更不用說(shuō)判斷配一張流程圖還是配一張插圖。3.2 LangChain / AutoGen 等Agent框架使用現(xiàn)成框架的好處是內(nèi)置了ReAct循環(huán)、工具注冊(cè)、調(diào)用鏈、記憶等能力寫(xiě)起來(lái)代碼精簡(jiǎn)。比如LangChain的initialize_agent配合Tool類(lèi)就能把search_image和generate_image掛到Agent上。但框架也存在學(xué)習(xí)成本和黑盒問(wèn)題。對(duì)自動(dòng)配圖這個(gè)任務(wù)來(lái)說(shuō)流程本身不算復(fù)雜框架沒(méi)有帶來(lái)決定性的優(yōu)勢(shì)。如果你已經(jīng)在項(xiàng)目里使用了某款A(yù)gent框架當(dāng)然可以基于它擴(kuò)展如果只是為了自動(dòng)配圖這一個(gè)功能引入整個(gè)框架有些重。3.3 自建輕量Agent第三條路線(xiàn)是自己寫(xiě)一個(gè)輕量Agent類(lèi)核心只有幾十行代碼。它的優(yōu)勢(shì)是完全可控你可以精確控制規(guī)劃內(nèi)容的JSON格式、工具函數(shù)返回的數(shù)據(jù)結(jié)構(gòu)、失敗重試邏輯。這條路線(xiàn)也最便于理解Agent開(kāi)發(fā)的核心原理后續(xù)遷移到框架時(shí)心里有底。我推薦第三種方案。原因有兩點(diǎn)配圖任務(wù)的工具數(shù)量較少一般兩個(gè)到五個(gè)足夠任務(wù)邊界清晰容錯(cuò)要求高自己寫(xiě)能夠做到逐級(jí)兜底。這篇文章的完整示例也基于自建輕量Agent展開(kāi)。3.4 取圖方式對(duì)比取圖又有兩種底層來(lái)源選型時(shí)需要考慮清楚維度圖庫(kù)搜索圖像生成版權(quán)風(fēng)險(xiǎn)需要篩選授權(quán)圖片風(fēng)險(xiǎn)由圖庫(kù)決定模型生成仍需注意內(nèi)容合規(guī)成本通常是搜索API配額或圖庫(kù)訂閱費(fèi)按張計(jì)費(fèi)成本較高風(fēng)格一致性不同圖片差異大需要后期處理通過(guò)提示詞條件統(tǒng)一風(fēng)格適圖場(chǎng)景技術(shù)配圖、實(shí)拍圖、新聞插圖插畫(huà)、概念圖、找不到合適素材時(shí)穩(wěn)定程度搜索結(jié)果受圖庫(kù)標(biāo)簽質(zhì)量影響受模型能力和提示詞影響實(shí)際項(xiàng)目里最穩(wěn)妥的是混合策略?xún)?yōu)先搜索搜索不到或語(yǔ)義不適配時(shí)再生成。代碼上也可以通過(guò)配置項(xiàng)切換策略。4. 環(huán)境準(zhǔn)備與前置條件這一節(jié)開(kāi)始進(jìn)入實(shí)操。以下環(huán)境是本文示例的推薦配置版本請(qǐng)以實(shí)際項(xiàng)目為準(zhǔn)我重點(diǎn)演示的是通用思路。4.1 基礎(chǔ)運(yùn)行環(huán)境操作系統(tǒng)Windows 10/11、macOS、Linux均可本文按macOS/Linux的bash命令演示W(wǎng)indows可在Git Bash中執(zhí)行。Python版本需要3.10及以上主要為了使用類(lèi)型注解和新版標(biāo)準(zhǔn)庫(kù)。包管理推薦使用venv或conda創(chuàng)建獨(dú)立虛擬環(huán)境。大模型API需要一個(gè)支持文本生成并返回結(jié)構(gòu)化JSON的模型接口本文示例使用OpenAI兼容接口的通用寫(xiě)法你可以替換為其他合規(guī)可用的模型服務(wù)。圖像生成或搜索API生成圖可以使用圖像生成模型接口搜索圖可以使用合規(guī)圖庫(kù)API。沒(méi)有API時(shí)也可以用本地圖片目錄模擬先跑通流程。4.2 創(chuàng)建項(xiàng)目目錄建議目錄結(jié)構(gòu)如下agent-autopicture/ ├── main.py # 程序入口 ├── agent.py # 輕量Agent核心邏輯 ├── tools.py # 工具函數(shù)搜圖、生成圖、下載 ├── config.py # 配置項(xiàng) ├── input/ │ └── article.md # 待配圖的文章 ├── output/ │ ├── images/ # 本地圖片 │ └── article_with_images.md # 配圖后的文章 └── requirements.txt # 依賴(lài)先在命令行執(zhí)行mkdir -p agent-autopicture/{input,output/images} cd agent-autopicture python3 -m venv venv source venv/bin/activate4.3 安裝依賴(lài)requirements.txt內(nèi)容如下openai1.30.0 requests2.31.0 markdown3.5.0然后安裝pip install -r requirements.txt需要說(shuō)明的是openai庫(kù)在這里只用于調(diào)用兼容OpenAI格式的模型服務(wù)如果你使用其他服務(wù)商請(qǐng)按對(duì)應(yīng)SDK文檔調(diào)整。關(guān)鍵設(shè)計(jì)是我們把模型調(diào)用封裝在同一個(gè)函數(shù)里后面替換模型服務(wù)時(shí)只需要改這一個(gè)地方。4.4 配置密鑰不建議把密鑰硬編碼在代碼里。在項(xiàng)目根目錄創(chuàng)建.env文件把API_KEY寫(xiě)入其中。示例中我們直接用環(huán)境變量讀取更穩(wěn)妥的做法是配合python-dotenv使用。這里先演示環(huán)境變量方式export AGENT_API_KEY你的模型服務(wù)密鑰 export AGENT_API_BASE模型服務(wù)地址 export AGENT_MODEL模型名稱(chēng)如果你在Windows PowerShell里運(yùn)行可以使用$env:AGENT_API_KEY你的模型服務(wù)密鑰 $env:AGENT_API_BASE模型服務(wù)地址 $env:AGENT_MODEL模型名稱(chēng)配置密鑰的核心原則是最小權(quán)限、不進(jìn)版本庫(kù)、區(qū)分環(huán)境。尤其是團(tuán)隊(duì)協(xié)作時(shí)不要為了省事把密鑰寫(xiě)進(jìn)代碼提交到Git倉(cāng)庫(kù)。5. Agent自動(dòng)配圖完整示例與代碼實(shí)現(xiàn)下面進(jìn)入正文最核心的部分。這一節(jié)會(huì)給出一個(gè)可以運(yùn)行的輕量Agent示例代碼量不大但把“規(guī)劃 - 工具調(diào)用 - 校驗(yàn) - 兜底”這一個(gè)完整鏈路跑通。5.1 配置文件 config.py配置文件負(fù)責(zé)集中管理模型參數(shù)、圖片策略、輸出目錄。它便于你在一處修改行為而不是在代碼中到處找。# 文件路徑agent-autopicture/config.py import os # 模型配置 MODEL_API_KEY os.getenv(AGENT_API_KEY, ) MODEL_API_BASE os.getenv(AGENT_API_BASE, ) MODEL_NAME os.getenv(AGENT_MODEL, gpt-4o-mini) # 配圖策略: search / generate / mixed IMAGE_STRATEGY os.getenv(IMAGE_STRATEGY, mixed) # 輸出結(jié)果 OUTPUT_IMAGE_DIR output/images OUTPUT_MARKDOWN_PATH output/article_with_images.md # 默認(rèn)每篇文章最多配圖數(shù)量 MAX_IMAGE_COUNT 6 # 圖片比例可取值 square / wide / tall IMAGE_RATIO square這段代碼把模型接口、策略和輸出位置都提出來(lái)了。IMAGE_STRATEGY建議先設(shè)為mixed這樣在搜圖失敗時(shí)還能走生成圖兜底。MAX_IMAGE_COUNT是安全邊界防止模型在長(zhǎng)文中生成過(guò)多配圖導(dǎo)致成本不可控。5.2 工具函數(shù) tools.py工具函數(shù)是Agent執(zhí)行層的關(guān)鍵。以搜索圖庫(kù)和生成圖片為例下面代碼演示通用接口寫(xiě)法不綁定具體廠商。你可以把它替換成自己的圖庫(kù)API或圖像生成服務(wù)。# 文件路徑agent-autopicture/tools.py import os import uuid import requests from pathlib import Path OUTPUT_IMAGE_DIR Path(output/images) def _download_image(url: str, save_dir: Path) - str: 下載圖片到本地并返回本地路徑 save_dir.mkdir(parentsTrue, exist_okTrue) suffix .jpg # 根據(jù)URL后綴判斷文件類(lèi)型無(wú)法判斷時(shí)默認(rèn)jpg if .png in url.lower(): suffix .png filename f{uuid.uuid4().hex}{suffix} local_path save_dir / filename resp requests.get(url, timeout20) resp.raise_for_status() local_path.write_bytes(resp.content) return str(local_path) def search_image(query: str, ratio: str square) - dict: 工具1在圖庫(kù)中搜索圖片返回候選圖片本地路徑或URL # 這里以合規(guī)圖庫(kù)API為例請(qǐng)?zhí)鎿Q為實(shí)際可用的圖庫(kù)服務(wù) # 如果未配置圖庫(kù)API則主動(dòng)拋出讓Agent走生成策略 api_key os.getenv(IMAGE_LIBRARY_KEY, ) if not api_key: return {success: False, reason: 未配置圖庫(kù)API密鑰請(qǐng)使用生成策略或補(bǔ)充密鑰} # 示例請(qǐng)求實(shí)際參數(shù)以圖庫(kù)文檔為準(zhǔn) search_url https://example-image-library.com/api/search params { query: query, orientation: landscape if ratio wide else square, per_page: 3, access_key: api_key, } resp requests.get(search_url, paramsparams, timeout20) if resp.status_code ! 200: return {success: False, reason: f圖庫(kù)請(qǐng)求失敗, code{resp.status_code}} items resp.json().get(results, []) if not items: return {success: False, reason: 沒(méi)有找到匹配圖片} first items[0] return {success: True, path: _download_image(first[url], OUTPUT_IMAGE_DIR)} def generate_image(prompt: str, ratio: str square) - dict: 工具2調(diào)用圖像生成模型生成圖片 # 這里使用OpenAI兼容接口的通用寫(xiě)法具體參數(shù)以服務(wù)商文檔為準(zhǔn) from openai import OpenAI client OpenAI( api_keyos.getenv(AGENT_API_KEY, ), base_urlos.getenv(AGENT_API_BASE, None), ) try: response client.images.generate( modelos.getenv(IMAGE_GEN_MODEL, dall-e-3), promptprompt, size1024x1024 if ratio square else 1792x1024, n1, ) image_url response.data[0].url return {success: True, path: _download_image(image_url, OUTPUT_IMAGE_DIR)} except Exception as e: return {success: False, reason: f圖像生成失敗: {e}}這段代碼有兩個(gè)關(guān)鍵點(diǎn)。第一search_image如果發(fā)現(xiàn)沒(méi)有配置圖庫(kù)密鑰會(huì)返回失敗原因而不是強(qiáng)行走錯(cuò)誤分支第二generate_image在生成失敗時(shí)會(huì)把異常信息打包返回給Agent。這種“失敗也要有結(jié)構(gòu)化信息”的習(xí)慣是Agent工具設(shè)計(jì)里很重要的一環(huán)。Agent只有拿到清晰的失敗原因才能決定是換關(guān)鍵詞搜索還是切換到生成策略。5.3 輕量Agent核心 agent.py接下來(lái)是Agent本體。它要做三件事調(diào)用模型生成配圖計(jì)劃、解析計(jì)劃、按計(jì)劃執(zhí)行工具。這里不依賴(lài)復(fù)雜框架核心是把模型輸出格式固定成JSON數(shù)組。# 文件路徑agent-autopicture/agent.py import json import re from openai import OpenAI from tools import search_image, generate_image from config import ( MODEL_API_KEY, MODEL_API_BASE, MODEL_NAME, IMAGE_STRATEGY, MAX_IMAGE_COUNT, IMAGE_RATIO, ) class AgentAutoPicture: 輕量自動(dòng)配圖Agent def __init__(self, api_key: str, api_base: str, model: str): self.client OpenAI(api_keyapi_key, base_urlapi_base or None) self.model model def _parse_plan(self, content: str) - list: 從模型輸出中解析JSON配圖計(jì)劃 # 有些模型會(huì)在代碼塊中返回JSON先嘗試提取 match re.search(r\[.*\], content, re.S) if not match: raise ValueError(模型輸出中沒(méi)有找到JSON配圖計(jì)劃) plan_text match.group(0) plan json.loads(plan_text) if not isinstance(plan, list): raise ValueError(配圖計(jì)劃必須是JSON數(shù)組) return plan def make_plan(self, article_text: str) - list: 第一步讓模型生成配圖計(jì)劃 prompt f 你是一個(gè)內(nèi)容配圖規(guī)劃師。請(qǐng)閱讀下面這篇文章規(guī)劃不超過(guò){MAX_IMAGE_COUNT}張配圖。 輸入文章 {article_text[:8000]} 輸出要求 1. 返回JSON數(shù)組每個(gè)元素包含四個(gè)字段position、topic、query、description。 2. position表示插在文章第幾段之后從1開(kāi)始。 3. topic表示這張圖的主題關(guān)鍵詞。 4. query表示用于搜索圖庫(kù)的英文檢索詞。 5. description表示如果搜索不到用于生成圖片的完整提示詞要寫(xiě)明畫(huà)面內(nèi)容、構(gòu)圖和風(fēng)格。 6. 只輸出JSON不要輸出解釋或其他內(nèi)容。 resp self.client.chat.completions.create( modelself.model, messages[ {role: system, content: 你是配圖計(jì)劃生成專(zhuān)家只返回JSON。}, {role: user, content: prompt}, ], temperature0.3, ) raw resp.choices[0].message.content return self._parse_plan(raw) def _execute_one(self, item: dict) - dict: 第二步執(zhí)行單條配圖任務(wù)支持mixed策略兜底 strategy IMAGE_STRATEGY if strategy in (search, mixed): result search_image(item[query], IMAGE_RATIO) if result[success]: return {**item, status: search_ok, image: result[path]} if strategy search: return {**item, status: search_failed, reason: result.get(reason)} if strategy in (generate, mixed): prompt item.get(description, item.get(topic, 配圖)) result generate_image(prompt, IMAGE_RATIO) if result[success]: return {**item, status: generate_ok, image: result[path]} return {**item, status: generate_failed, reason: result.get(reason)} return {**item, status: failed, reason: 未知策略} def run(self, article_text: str) - list: 完整執(zhí)行規(guī)劃 配圖 plan self.make_plan(article_text) results [] for item in plan: results.append(self._execute_one(item)) return results這個(gè)輕量Agent的巧妙之處在于它把模型規(guī)劃結(jié)果當(dāng)作“中間數(shù)據(jù)”而不是最終答案。make_plan只負(fù)責(zé)產(chǎn)出JSON計(jì)劃_execute_one則負(fù)責(zé)工具調(diào)度。即使模型輸出里的query搜索不到圖也還有description可以走生成鏈路這就是Agent相對(duì)普通腳本的核心優(yōu)勢(shì)它可以基于失敗結(jié)果調(diào)整行為。5.4 圖片插入與主程序 main.pyAgent返回的結(jié)果是一個(gè)包含圖片路徑和插入位置的列表。我們需要把它們寫(xiě)回Markdown文章。這里做的是最直接的插入方式在指定段落后插入。# 文件路徑agent-autopicture/main.py import sys from pathlib import Path from agent import AgentAutoPicture from config import MODEL_API_KEY, MODEL_API_BASE, MODEL_NAME, OUTPUT_MARKDOWN_PATH INPUT_PATH Path(input/article.md) def read_article(path: Path) - str: return path.read_text(encodingutf-8) def split_markdown_paragraphs(text: str) - list: 按空行拆分成段落保持原有Markdown結(jié)構(gòu) return text.strip().split(\n\n) def insert_images(article_text: str, results: list) - str: 把圖片插入到對(duì)應(yīng)段落后面 paragraphs split_markdown_paragraphs(article_text) # 按position降序插入避免后面插入影響前面索引 for item in sorted(results, keylambda x: x.get(position, 1), reverseTrue): if item.get(status) not in (search_ok, generate_ok): continue pos int(item.get(position, 1)) if 0 pos len(paragraphs): image_line f\n\n paragraphs.insert(pos 1, image_line) return \n\n.join(paragraphs) def main(): if not MODEL_API_KEY: print(請(qǐng)先設(shè)置 AGENT_API_KEY 環(huán)境變量) sys.exit(1) article_text read_article(INPUT_PATH) agent AgentAutoPicture(api_keyMODEL_API_KEY, api_baseMODEL_API_BASE, modelMODEL_NAME) results agent.run(article_text) new_article insert_images(article_text, results) out_path Path(OUTPUT_MARKDOWN_PATH) out_path.parent.mkdir(parentsTrue, exist_okTrue) out_path.write_text(new_article, encodingutf-8) print(配圖完成輸出文件, out_path) for item in results: print(item.get(position), item.get(status), item.get(image, item.get(reason))) if __name__ __main__: main()這里有一個(gè)容易踩的坑在列表中間不斷插入內(nèi)容時(shí)如果按原始段落索引從前向后插入后面的插入位置會(huì)因?yàn)榍懊嫘略鰞?nèi)容而錯(cuò)位。解決方法是先按position降序排序從后往前插入這樣前面插入的圖片不會(huì)影響后面已經(jīng)計(jì)算好的位置。這是處理Markdown或HTML內(nèi)容動(dòng)態(tài)插入時(shí)很實(shí)用的技巧。5.5 運(yùn)行命令與預(yù)期結(jié)果準(zhǔn)備一篇待配圖的文章。例如input/article.md內(nèi)容可以是一段技術(shù)分享包含“背景、方案、實(shí)現(xiàn)、總結(jié)”幾個(gè)Parts。然后運(yùn)行python main.py程序會(huì)依次執(zhí)行“生成配圖計(jì)劃”和“搜索/生成圖片”。預(yù)期輸出類(lèi)似配圖完成輸出文件 output/article_with_images.md 2 search_ok output/images/xxx.jpg 5 generate_ok output/images/xxx.png 7 search_failed 圖庫(kù)沒(méi)有找到匹配圖片看到配圖完成說(shuō)明主流程跑通了。打開(kāi)output/article_with_images.md應(yīng)該能看到在指定段落后出現(xiàn)圖片引用。注意某些圖片下載后可能是無(wú)效文件所以要靠下一步的校驗(yàn)來(lái)兜底。6. 運(yùn)行結(jié)果與效果驗(yàn)證跑通流程只是第一步驗(yàn)證輸出質(zhì)量才是真正體現(xiàn)工程能力的地方。這一節(jié)提供一套簡(jiǎn)單有效的驗(yàn)證方案分為文件級(jí)驗(yàn)證、圖片級(jí)驗(yàn)證和內(nèi)容級(jí)驗(yàn)證。6.1 文件級(jí)驗(yàn)證檢查圖片文件是否存在且非空l(shuí)s -lh output/images/如果看到多個(gè).jpg或.png文件且大小不為0說(shuō)明下載或生成成功。如果文件大小只有幾KB并且打不開(kāi)大概率是圖庫(kù)返回了錯(cuò)誤占位圖或圖片下載不完整。6.2 Markdown鏈接驗(yàn)證使用Python腳本檢查圖片引用是否與實(shí)際文件對(duì)應(yīng)# 文件路徑agent-autopicture/validate.py import re from pathlib import Path md_path Path(output/article_with_images.md) text md_path.read_text(encodingutf-8) image_refs re.findall(r!\[.*?\]\((.*?)\), text) for ref in image_refs: img_path Path(ref) if not img_path.exists(): print(f缺失圖片: {ref}) else: print(fOK: {ref} - {img_path.stat().st_size} bytes)這個(gè)腳本的好處是能在輸出團(tuán)隊(duì)交付前提前發(fā)現(xiàn)斷鏈問(wèn)題。特別是當(dāng)圖片來(lái)自臨時(shí)下載目錄、遠(yuǎn)程URL或圖床時(shí)斷鏈非常容易被忽略。6.3 內(nèi)容級(jí)驗(yàn)證檢查配圖位置是不是和段意思搭配合理。這一步無(wú)法完全自動(dòng)化但可以做一個(gè)低成本的“采樣檢查”隨機(jī)抽3張配圖先看圖片和段落主題的相關(guān)性再看整體風(fēng)格是否統(tǒng)一。如果走的是搜索策略圖片風(fēng)格不一致屬于正?，F(xiàn)象如果走的是生成策略模型輸出風(fēng)格受提示詞影響可以在description里統(tǒng)一加入“扁平插畫(huà)風(fēng)格簡(jiǎn)潔背景”這類(lèi)限定詞。運(yùn)行失敗的排錯(cuò)思路從下往上先看是否有API錯(cuò)誤再看規(guī)劃JSON是否被正確解析再看工具調(diào)用返回的失敗原因最后看圖片文件是否存在。在代碼里每一環(huán)都有結(jié)構(gòu)化狀態(tài)值使用search_ok、generate_ok、search_failed這樣的狀態(tài)碼能節(jié)省大量定位時(shí)間。7. 常見(jiàn)問(wèn)題與排查思路自動(dòng)配圖Agent在真實(shí)環(huán)境中會(huì)遇到各種問(wèn)題。下面表格列出最常見(jiàn)的幾類(lèi)以及對(duì)應(yīng)的排查方式。問(wèn)題現(xiàn)象可能原因排查方式解決方案啟動(dòng)后提示API密鑰無(wú)效密鑰未設(shè)置或設(shè)置錯(cuò)誤檢查環(huán)境變量是否生效打印密鑰前幾位和后幾位重新設(shè)置密鑰確認(rèn)密鑰所屬服務(wù)與base地址一致模型返回的不是JSON提示詞約束不足或模型版本較弱打印原始輸出看是文本解釋還是被截?cái)嘣鰪?qiáng)提示詞要求“只返回JSON”或使用JSON Mode配圖計(jì)劃數(shù)量超出預(yù)期提示詞沒(méi)嚴(yán)格限制條數(shù)檢查生成的計(jì)劃列表長(zhǎng)度在代碼里截?cái)酁镸AX_IMAGE_COUNT并優(yōu)化提示詞圖片下載為空文件圖庫(kù)返回了占位圖或下載超時(shí)檢查文件大小用瀏覽器打開(kāi)URL測(cè)試下載前校驗(yàn)Content-Type和Content-Length增加超時(shí)重試生成圖接口報(bào)余額不足圖像生成模型費(fèi)用高于預(yù)期查看服務(wù)商賬單和限額改用mixed策略能搜圖就不生成設(shè)置每日消耗上限插入位置錯(cuò)亂列表插入時(shí)索引變化檢查position字段和段落數(shù)量使用降序插入邏輯從后往前插入圖片風(fēng)格不統(tǒng)一搜索圖庫(kù)來(lái)自不同來(lái)源檢查候選圖縮略圖在query后追加風(fēng)格詞或全量切換為生成策略長(zhǎng)文截?cái)鄬?dǎo)致計(jì)劃不完整文章超過(guò)模型上下文長(zhǎng)度檢查文章長(zhǎng)度和日志截?cái)帱c(diǎn)分段摘要再規(guī)劃或只對(duì)前8000字符做規(guī)劃這里想重點(diǎn)提醒“圖片版權(quán)”問(wèn)題。圖庫(kù)搜索得到的結(jié)果不一定都允許商用生成模型合成圖片也存在內(nèi)容合規(guī)風(fēng)險(xiǎn)。在生產(chǎn)環(huán)境中工具層應(yīng)該加入一個(gè)check_license步驟從圖庫(kù)返回結(jié)果中讀取授權(quán)信息把未明示授權(quán)的候選圖過(guò)濾掉。不要為了流程自動(dòng)化把版權(quán)審核也自動(dòng)省略了。8. 最佳實(shí)踐與工程建議當(dāng)自動(dòng)配圖Agent從“能跑”到“好用”需要補(bǔ)上很多工程細(xì)節(jié)。我按實(shí)際項(xiàng)目中最重要的幾條來(lái)總結(jié)。8.1 提示詞與JSON結(jié)構(gòu)分離規(guī)劃階段使用的提示詞要盡可能描述清楚輸出JSON的結(jié)構(gòu)甚至在提示詞中附上一個(gè)小示例。更好的做法是在系統(tǒng)提示詞中聲明“只輸出合法JSON”同時(shí)在用戶(hù)提示詞中再給一個(gè)結(jié)構(gòu)示例。對(duì)于需要頻繁調(diào)整的業(yè)務(wù)可以把提示詞抽成單獨(dú)的文件避免為了改一行字重新部署代碼。8.2 圖片文件管理必須有規(guī)范和緩存每次運(yùn)行都重新下載圖片會(huì)造成大量重復(fù)文件。生產(chǎn)實(shí)踐是建立以“文章ID 內(nèi)容哈?！睘槟夸浀膱D片存儲(chǔ)結(jié)構(gòu)例如output/ └── article_1234/ ├── images/ │ ├── plan.json │ └── key_image_001.png └── article_with_images.md這樣同一篇文章重復(fù)配圖時(shí)如果內(nèi)容哈希沒(méi)變可以直接復(fù)用已有結(jié)果既節(jié)省API費(fèi)用也避免生成多份不一致的圖片。8.3 成本控制是自動(dòng)化的生命線(xiàn)自動(dòng)配圖的成本大頭來(lái)自大模型調(diào)用和圖像生成。設(shè)計(jì)上至少要加三個(gè)控制點(diǎn)單篇文章最大配圖數(shù)量、每日總調(diào)用次數(shù)、圖像生成失敗自動(dòng)降級(jí)為搜索。還應(yīng)該在config.py中設(shè)置每日預(yù)算當(dāng)超出時(shí)直接停止新任務(wù)。8.4 Agent記憶與Skills擴(kuò)展方向當(dāng)任務(wù)從一個(gè)Agent擴(kuò)展到多個(gè)Agent時(shí)可以引入Agent記憶。例如保存“某個(gè)領(lǐng)域文章的配圖風(fēng)格偏好”下次同類(lèi)任務(wù)直接讀取減少重復(fù)規(guī)劃。Skills則是把“版權(quán)審核”“圖片壓縮”“風(fēng)格遷移”拆成獨(dú)立能力模塊。這些擴(kuò)展不等于要在第一天全做但代碼設(shè)計(jì)上要給接口留擴(kuò)展位。比如讓_execute_one支持注冊(cè)新的工具函數(shù)而不是把所有邏輯都寫(xiě)在同一個(gè)if分支里。8.5 安全邊界與內(nèi)容合規(guī)自動(dòng)配圖涉及外部圖片下載和生成存在內(nèi)容安全風(fēng)險(xiǎn)。建議在工具鏈中增加圖片審核步驟尤其是涉及人物、品牌、地圖等敏感類(lèi)別時(shí)先用視覺(jué)模型打標(biāo)命中敏感類(lèi)別則丟棄候選圖。生成圖像提示詞也應(yīng)該有一個(gè)負(fù)面過(guò)濾列表防止出現(xiàn)不合規(guī)內(nèi)容。從工程角度說(shuō)自動(dòng)配圖腳本運(yùn)行的賬號(hào)權(quán)限應(yīng)按最小權(quán)限配置不隨便下載未知來(lái)源文件并執(zhí)行。8.6 日志與可觀測(cè)性給Agent運(yùn)行加上結(jié)構(gòu)化日志而不是只打印一行“配圖完成”。每次工具調(diào)用都應(yīng)該記錄調(diào)用時(shí)間、輸入?yún)?shù)、返回狀態(tài)、耗時(shí)、圖片大小。這些日志不只是為了排障更是為了后續(xù)復(fù)盤(pán)“哪一類(lèi)文章適合搜索策略哪一類(lèi)適合生成策略”。沒(méi)有日志Agent優(yōu)化就只能靠猜。9. 總結(jié)與后續(xù)學(xué)習(xí)方向這篇文章從“配圖如何自動(dòng)化”切入講清楚了Agent自動(dòng)配圖的原理、選型和落地鏈路。核心不是讓模型生成一張圖而是讓Agent能夠穩(wěn)定地完成從“讀文章”到“規(guī)劃配圖”再到“調(diào)用工具獲得圖片、插入文檔”的完整決策閉環(huán)。通過(guò)一個(gè)輕量Agent示例我們演示了JSON規(guī)劃、工具調(diào)用、降級(jí)策略、批量插入和結(jié)果校驗(yàn)這套代碼可以直接改造成你自己的內(nèi)容生產(chǎn)工具的一部分。如果你要繼續(xù)深入Agent開(kāi)發(fā)下面幾個(gè)方向值得依次探索。第一個(gè)方向是工具能力擴(kuò)展給Agent增加圖片壓縮、水印、風(fēng)格統(tǒng)一、色彩分析等工具讓它在取到圖之后還能繼續(xù)后處理。第二個(gè)方向是Agent記憶保存歷史配圖偏好并在新任務(wù)中自動(dòng)復(fù)用減少模型重復(fù)規(guī)劃帶來(lái)的不一致。第三個(gè)方向是Multi-Agent協(xié)作讓“內(nèi)容理解Agent”“配圖規(guī)劃Agent”“圖片審核Agent”各自負(fù)責(zé)單一職責(zé)通過(guò)共享任務(wù)隊(duì)列協(xié)作這更接近團(tuán)隊(duì)協(xié)作的模式。第四個(gè)方向是Skills沉淀把你常用的提示詞、工具函數(shù)、校驗(yàn)規(guī)則打包成可復(fù)用的Skill后續(xù)接入LangChain或其他Agent框架時(shí)可以直接平移過(guò)去。動(dòng)手時(shí)有個(gè)建議先用最小示例跑通“標(biāo)題配圖”的場(chǎng)景輸入只要一句話(huà)比如“幫我寫(xiě)一篇數(shù)據(jù)庫(kù)遷移的文章并配圖”確認(rèn)Agent能完成規(guī)劃、取圖、插入三個(gè)動(dòng)作后再逐步擴(kuò)大到長(zhǎng)文章和復(fù)雜文檔。每一步都補(bǔ)充日志和校驗(yàn)才能讓自動(dòng)配圖從“偶爾能用”變成“穩(wěn)定可用”。你自己的內(nèi)容創(chuàng)作流程也不用再被一張找不到的配圖卡住。