在 AI 绘图与视觉内容生成工作流里提示词一直是决定成片质量的关键但也是大多数人最容易卡住的地方。用户往往只输入“一只猫在窗台上看月亮”这样的自然语言真正下发到 MiniMax H3 这类生成模型时却需要包含主体、环境、镜头、光影、画质修饰词等结构化信息。本文围绕 MiniMax H3 提示词优化场景讲解如何用 Gemma 系列轻量模型在本地完成提示词改写再封装成 HTTP API最后通过绘世Stable Diffusion WebUI 整合包插件接入绘图流程形成一条“自然语言 - 优化提示词 - 调用生成模型”的自动化链路同时覆盖提速、缓存、并发和常见排错策略。在实际项目中提示词优化并不是简单地在原有句子上拼接几个英文标签。它需要理解用户意图、匹配目标模型的语言习惯、控制长度与权重还要考虑推理速度。如果每次写提示词都依赖远程大模型既会引入网络延迟也可能带来隐私和数据成本问题。把 Gemma 这类开源轻量模型部署在本地并做一层 API 封装就能在延迟、成本和可控性之间取得平衡。1. 提示词优化要先看数据链路而不是只看模型很多人一提到提示词优化第一反应是找更好的 Prompt 模板或者换一个更聪明的大模型。但在实际工作流里真正决定体验的是整条数据链路用户输入进入系统后经过哪些处理由谁改写改写结果给谁消费中间如何缓存和失败回退。只有先把这条链路定下来模型选择才有意义。1.1 为什么本地轻量模型适合做提示词优化提示词优化任务有一个特点输入和输出都是短文本逻辑相对简单但对延迟敏感。用户在绘图界面等一个提示词等待时间通常不能超过几秒。云端大模型虽然能力更强但网络往返和排队时间会让体验明显下降。本地轻量模型的好处是把推理放在自己机器上延迟可控离线可用也不会把用户输入发送到第三方服务。以 Gemma 系列为例它提供从几十亿到几百亿参数的不同版本经过量化后可以运行在消费级显卡上。这类模型经过微调后理解指令的能力并不弱处理“把自然语言改写成结构化绘图提示词”这种任务完全够用。标题里提到的 Gemma4 具体版本和量化格式要以实际发布的模型文件为准本地说法并不重要关键思路是用足够小、足够快的模型承担提示词优化这一环。选择本地模型时要关注三件事参数量与显存是否匹配通常 7B 到 14B 的量化模型是起步选择。上下文长度是否满足提示词模板需求至少 4K 比较稳妥。指令跟随能力是否稳定建议用同一组测试用例跑几轮确认输出格式不会飘。1.2 MiniMax H3 在链路中的位置MiniMax H3 在本文场景里作为最终消费提示词的生成模型。也就是说提示词优化服务产出的不是最终画面而是给 MiniMax H3 使用的输入指令。两者分工可以这样理解用户层输入自然语言比如“赛博朋克风格的雨夜街道霓虹灯倒影”。优化层输出结构化的 MiniMax H3 提示词比如包含主体、环境、光照、构图、风格、负面词。生成层调用MiniMax H3 收到优化后的提示词输出图片或视频。这个分工不限于具体某个模型。只要生成模型有相对固定的提示词偏好就可以在前面加一层优化服务。这样即使未来换了底层生成模型也只需要调整提示词模板不需要重写用户入口。1.3 一条完整的优化链路推荐按下面这条链路搭建用户输入自然语言 - 前端/绘图插件 - 本地提示词优化 APIGemma 模型 - 结构化提示词 - MiniMax H3 等生成模型 - 图片/视频结果链路中有两个接口要重点设计输入接口接收用户自然语言和可选参数例如风格、画幅比例、负面词。输出接口返回优化后的提示词文本同时附带解析耗时、是否命中缓存、模型名称等调试信息。这条链路跑通之后可以继续增加缓存层、模板层、失败回退层逐步变成生产可用的提示词服务。2. 环境准备先把模型和 API 服务跑起来在写代码之前先把运行环境准备好。提示词优化 API 服务本身依赖 Python 和模型推理运行时客户端则是绘世整合包里的 Stable Diffusion WebUI两者可以部署在同一台机器上也可以分开部署。2.1 依赖与模型选择推荐使用 Ollama 作为本地模型运行时。它支持 Gemma 系列模型内部处理了量化、显存管理和原生 HTTP 接口比自己用 transformers 写推理代码要省事得多。需要安装的组件包括Python 3.10 或更高版本。Ollama用于加载和管理 Gemma 模型。FastAPI 和 Uvicorn用于提供提示词优化 API 服务。绘世整合包或者任意 Stable Diffusion WebUI 环境用于验证插件调用。如果不想使用 Ollama也可以使用 llama.cpp 的 server 模式或者 Hugging Face Transformers。下面示例以 Ollama 为主因为它接口简单适合快速验证。2.2 用 Ollama 启动 Gemma 模型先确认 Ollama 安装成功ollama --version如果没有安装可以到 Ollama 官网下载对应系统版本。安装完成后拉取 Gemma 系列模型ollama pull gemma3:4b这里以 4B 量化模型为例。如果你使用的是标题中提到的“Gemma4”版本需要先确认该版本是否已经发布到模型仓库再替换模型名。如果机器显存更高比如 16GB 以上可以尝试更大的 12B 或 27B 量化版。拉取完成后启动并检查模型能否正常对话ollama run gemma3:4b 请用一句话介绍你是什么模型。看到正常回复后说明模型运行时没问题。Ollama 默认提供一个本地 HTTP 接口地址是http://localhost:11434/api/generate后续我们的 API 服务会调用这个接口。2.3 环境检查清单建议在继续前按这个清单检查一遍避免后面接口联调时反复找原因。检查项检查命令或方式通过标准Python 版本python --version3.10 或更高Ollama 服务ollama serve端口 11434 能被访问模型文件ollama list目标模型处于 available 状态显卡驱动nvidia-smi能显示显存和驱动版本绘图环境启动绘世 WebUI浏览器能打开前端页面注意学习环境只需要把链路跑通生产环境则要再考虑权限、日志、监控和回滚不能把本机启动当作部署完成。3. 实现提示词优化 API 服务这一节会写一个完整的 FastAPI 服务把本地 Gemma 模型包装成提示词优化接口。接口接收用户自然语言返回优化后的提示词并附带一些调试信息。3.1 FastAPI 服务骨架创建项目目录mkdir prompt-optimizer cd prompt-optimizer创建虚拟环境并安装依赖python -m venv .venv source .venv/bin/activate pip install fastapi uvicorn httpx pydantic在项目里创建main.py先实现服务骨架from fastapi import FastAPI from pydantic import BaseModel, Field import httpx import time app FastAPI(titleLocal Prompt Optimizer) OLLAMA_URL http://localhost:11434/api/generate MODEL_NAME gemma3:4b class OptimizeRequest(BaseModel): user_prompt: str Field(..., description用户输入的自然语言) style: str Field(, description可选风格例如 cyberpunk, realistic, anime) negative_prompt: str Field(, description可选负面词) class OptimizeResponse(BaseModel): optimized_prompt: str model: str elapsed_ms: int cached: bool False app.post(/optimize, response_modelOptimizeResponse) async def optimize_prompt(req: OptimizeRequest): start time.time() optimized await call_gemma(req) elapsed int((time.time() - start) * 1000) return OptimizeResponse( optimized_promptoptimized, modelMODEL_NAME, elapsed_mselapsed, ) async def call_gemma(req: OptimizeRequest) - str: # 下一步实现 return 这个骨架定义了两个数据模型请求参数包括user_prompt、style和negative_prompt响应体里携带了模型名和耗时。后续做缓存时cached字段会用来标记是否命中缓存。3.2 提示词优化函数call_gemma是核心函数要构造指令并调用 Ollama 接口。这里的关键不是让模型自由发挥而是通过系统提示词固定输出格式。SYSTEM_PROMPT 你是一个专业的 AI 绘图提示词优化助手。 请把用户的自然语言改写成适合 MiniMax H3 等生成模型使用的提示词。 要求 1. 使用中文描述主体、环境、光线、构图、风格。 2. 如果用户给出了风格在提示词开头说明。 3. 输出控制在 120 个中文字符以内。 4. 只输出提示词本身不要解释不要加引号。 async def call_gemma(req: OptimizeRequest) - str: user_content req.user_prompt.strip() if req.style: user_content f风格{req.style}\n用户需求{req.user_prompt} payload { model: MODEL_NAME, prompt: user_content, system: SYSTEM_PROMPT, stream: False, options: { temperature: 0.7, max_tokens: 256, }, } async with httpx.AsyncClient(timeout30) as client: resp await client.post(OLLAMA_URL, jsonpayload) resp.raise_for_status() data resp.json() text data.get(response, ).strip() return text这段代码做了三件事构造包含系统指令和用户需求的完整请求。调用 Ollama 的/api/generate接口关闭流式输出。从返回的 JSON 中取出response字段。温度设置为 0.7是平衡随机性和稳定性的常见值。如果发现输出经常跑偏可以降到 0.3 左右。max_tokens限制为 256防止模型输出过长影响下游生成。3.3 参数说明Ollama 接口中几个关键参数需要理解否则出了问题不好排查。参数含义常用值错误表现temperature采样温度越高越随机0.3 - 0.8过高时提示词结构不稳定max_tokens最大输出 token 数128 - 512过短时提示词被截断system系统提示词见示例不设置时输出格式不稳定stream是否流式返回falsetrue 时响应结构不同这里的“错误表现”不是绝对规律而是常见现象。实际项目中需要根据你自己的模型和业务反复调整。3.4 启动与验证在本机启动服务uvicorn main:app --host 0.0.0.0 --port 8100用 curl 验证接口curl -X POST http://localhost:8100/optimize \ -H Content-Type: application/json \ -d {user_prompt: 一只橘猫在窗台上看月亮, style: cinematic}正常返回示例{ optimized_prompt: 电影感画面一只橘猫坐在窗台上抬头看月亮月光洒入房间背景虚化构图居中细节丰富, model: gemma3:4b, elapsed_ms: 812, cached: false }如果这一步通过了说明 API 服务已经具备被外部插件调用的能力。接下来要做的是让绘世 WebUI 里的按钮把提示词送到这个接口。4. 在绘世 SD WebUI 中通过插件接入绘世整合包内置了 Stable Diffusion WebUI而 WebUI 自带 HTTP API 和扩展机制。这里的常见需求是用户在图生图或文生图界面写好自然语言点击一个按钮自动把优化后的提示词回填到输入框。实现方式可以是一个前端脚本扩展也可以是一个更完整的后端插件。4.1 绘世 API 与插件机制说明Stable Diffusion WebUI 的 API 接口通常以/sdapi/v1/...开头插件则放在extensions目录下。插件可以包含 Python 后端代码也可以包含 JavaScript 前端脚本。在绘世整合包里典型的插件目录结构如下extensions/ prompt-optimizer/ scripts/ main.py javascript/ prompt_optimizer.js install.py README.md由于绘世本身就是基于 Stable Diffusion WebUI 的整合包官方对扩展机制的限制比较少插件可以在 WebUI 启动时被自动加载。如果绘世版本较老可能需要手动在启动参数中开启 API。4.2 插件核心代码这里用一个最小方案通过 WebUI 的scripts目录注册脚本在文生图页面上增加一个“优化提示词”按钮点击后把当前正向提示词发送到http://localhost:8100/optimize再把返回的优化结果回填。创建extensions/prompt-optimizer/scripts/main.pyimport gradio as gr from modules import script_callbacks def optimize_and_fill(prompt): import requests import json resp requests.post( http://localhost:8100/optimize, json{user_prompt: prompt}, timeout30 ) if resp.status_code 200: data resp.json() return data.get(optimized_prompt, prompt) return prompt def on_ui_tabs(): with gr.Blocks() as demo: with gr.Row(): input_text gr.Textbox(label自然语言输入, lines4) output_text gr.Textbox(label优化结果, lines4) btn gr.Button(优化提示词) btn.click( optimize_and_fill, inputsinput_text, outputsoutput_text ) return [(demo, 提示词优化)] script_callbacks.on_ui_tabs(on_ui_tabs)这段代码注册了一个新的 Tab 页面用户可以在页面上输入自然语言点击按钮后得到优化结果。如果要回填到默认的文生图输入框需要额外调用 WebUI 的前端接口或者把优化结果复制粘贴。4.3 插件配置为了让插件适应不同环境把优化服务地址提取到配置里。可以在scripts/main.py中读取环境变量import os OPTIMIZER_URL os.getenv(PROMPT_OPTIMIZER_URL, http://localhost:8100/optimize)在绘世启动脚本中设置环境变量即可export PROMPT_OPTIMIZER_URLhttp://127.0.0.1:8100/optimize生产环境下不要写死地址建议通过配置文件或环境变量维护。4.4 验证端到端流程启动绘世 WebUI 后打开浏览器进入“提示词优化”Tab输入“一只橘猫在窗台上看月亮”点击“优化提示词”。预期结果下方输出框中出现结构化的中文提示词。提示词优化服务日志显示 200 响应。MiniMax H3 或其它生成模型能根据优化后的提示词正常出图。端到端验证完成后可以认为这条链路是可用的。但距离生产使用还有差距因为尚未考虑速度优化和异常分支。5. 提速优化量化、缓存、并发和模板标题里提到“提速”所以这一节专门讲如何让提示词优化服务更快、更省资源。提速不是单点优化而是从模型部署、请求处理、业务逻辑三个层面分别下手。5.1 用量化模型降低推理开销在 Ollama 中同一个模型往往有不同量化等级。量化等级越低显存占用越小推理速度越快但输出质量可能会有轻微下降。可以用ollama list查看模型大小也可以按需拉取不同量化版本ollama pull gemma3:4b-q4_K_M ollama pull gemma3:4b-q8_0如果你的显卡显存有限推荐从q4_K_M开始试。这个版本在大多数 4B 模型上兼顾速度和质量。显存更充裕时再尝试更大模型。在 API 服务里把模型名称做成配置避免每次修改代码MODEL_NAME os.getenv(OPTIMIZER_MODEL, gemma3:4b-q4_K_M)5.2 提示词缓存设计同一个用户需求在短时间内反复提交是很常见的。如果每次请求都调用模型浪费算力且增加延迟。可以引入内存缓存。from functools import lru_cache lru_cache(maxsize256) def cached_optimize(user_prompt: str, style: str, negative_prompt: str) - str: # 这里调用模型但只有第一次执行 return optimized result使用lru_cache的注意点是输入参数必须可哈希并且缓存只能存在单进程内。如果服务部署在多个节点要改成 Redis 等外部缓存。命中缓存后接口响应时间可以从几百毫秒降到几毫秒这是成本最低的提速手段。5.3 并发与超时设置本地模型推理时多路同时请求容易导致显存不足或队列堆积。Ollama 默认串行处理单模型请求但可以通过OLLAMA_NUM_PARALLEL环境变量控制并行数。在 API 服务这一侧需要使用asyncio.Semaphore限制并发请求数import asyncio semaphore asyncio.Semaphore(2) async def call_gemma_with_limit(req: OptimizeRequest) - str: async with semaphore: return await call_gemma(req)超时设置同样重要。如果 Ollama 卡住请求会一直占用连接。在 httpx 客户端里设置连接超时和读取超时timeout httpx.Timeout(connect5.0, read60.0, write10.0, pool5.0)并发数 2 是保守起步值具体要根据显卡显存和模型大小调整。如果把模型换成了更大的 27B 版本并发数要降到 1。5.4 针对 MiniMax H3 的提示词模板提示词优化服务的目标是让生成模型更容易理解。不同生成模型对提示词格式的偏好不同。MiniMax H3 如果更偏好中文描述优化服务就输出中文如果更偏好英文标签则需要让 Gemma 模型输出英文。可以通过系统提示词控制输出语言和结构SYSTEM_PROMPT_EN You are a prompt optimizer for image generation. Convert user input into English tags. Separate tags with commas. Do not output explanations. 建议准备多套模板通过请求参数选择模板名称适用场景输出示例中文描述式中文生成模型电影感画面一只橘猫坐在窗台上英文标签式英文提示词模型cinematic, orange cat, window, moonlight结构分句式视频生成模型主体橘猫。环境窗台。光照月光模板不是越多越好而是要对齐下游模型的偏好。这里的核心原则是提示词优化服务不追求“优美的中文”而是追求“下游模型可理解的结构”。6. 常见问题与排查路径本地服务加插件调用常见的报错集中在网络连通、模型加载、参数格式和数据解析几类。下面给出一条排查顺序和常见问题速查表。6.1 报错排查顺序当优化接口失败时按这个顺序查看绘世 WebUI 前端有没有报错。看提示词优化服务的日志有没有异常。用 curl 单独调用/optimize确认服务本身是否正常。查看 Ollama 是否在运行ollama list是否能看到模型。检查端口是否能连通curl http://localhost:11434/api/tags。检查显卡显存确认模型是否被其他程序占用。最后检查代码里的参数名和返回字段有没有拼写错误。先检查数据是否到达再检查模型是否推理最后检查结果是否被正确解析这条路径可以避免在错误层浪费时间。6.2 常见问题速查表问题现象常见原因检查方式处理建议请求返回 404绘世插件地址错误或服务未启动检查 uvicorn 启动日志修正PROMPT_OPTIMIZER_URL返回 500Ollama 未运行或模型未拉取运行ollama list启动 Ollama 并拉取模型响应很慢并发过大或模型过大查看显存占用和 CPU 使用率降低并发数使用较小量化模型输出格式不稳定系统提示词缺少格式约束查看模型原始输出增强系统提示词降低 temperature提示词被截断max_tokens设置过小查看响应字段是否完整调大max_tokens插件按钮无反应浏览器控制台报跨域或脚本错误打开开发者工具查看 Console确认插件 JS 被加载确认 API 地址可访问6.3 三个高频坑第一个坑是直接用localhost调用其他服务但绘世 WebUI 和优化服务不一定在同一台机器。如果分开部署要把地址改成实际 IP并确保防火墙放行端口。第二个坑是修改了系统提示词后发现输出结果没有变化。原因是 Ollama 可能缓存了模型上下文或者请求拼接时覆盖了系统提示词。可以在调用前显式传入system字段并确认代码里没有把系统提示词和用户输入拼接混在一起。第三个坑是把缓存看得太重导致用户改了一次风格后仍返回旧结果。用lru_cache做缓存时要保证style和negative_prompt也作为缓存 key。如果使用 Redis 做缓存还要设置过期时间避免过期结果长期占用。7. 生产环境落地建议如果只是自己本机玩前面内容已经够用。如果要把这个提示词优化服务稳定地提供给团队或线上业务还需要补上部署、监控、安全等环节。7.1 服务化部署不要把 FastAPI 服务直接暴露在公网。推荐用 Nginx 或 Caddy 做反向代理并加上访问密钥。启动命令可以参考uvicorn main:app --host 127.0.0.1 --port 8100 --workers 1注意--workers 1是因为当前进程内有lru_cache多 worker 会导致缓存各持一份并且多进程同时调用 Ollama 会增加显存压力。生产环境多实例部署时应把缓存迁到 Redis。7.2 监控与日志在 FastAPI 中添加一个简单的请求日志中间件from fastapi import Request import logging logger logging.getLogger(optimizer) app.middleware(http) async def log_requests(request: Request, call_next): start time.time() response await call_next(request) elapsed int((time.time() - start) * 1000) logger.info( path%s status%s elapsed_ms%d, request.url.path, response.status_code, elapsed, ) return response生产环境还应监控接口延迟的 P50、P95 值。Ollama 队列长度。显存占用率。缓存命中率。这些指标能帮助你判断何时该扩容、何时该换模型。7.3 发布前检查清单在发布前按这个清单逐项确认检查项完成标准配置外置API 地址、模型名称、并发数不写死在代码中异常处理模型调用失败时有兜底提示词不让用户拿到空结果超时设置上游调用和下游调用都有明确超时缓存策略缓存 key 包含风格和负面词有有效期日志输出关键请求有耗时、状态码和错误信息权限控制内部 API 增加令牌校验回滚方案保留上一个可用的模型版本和配置文件7.4 扩展方向这条链路跑通后可以继续做三件事将提示词优化服务接入 ComfyUI通过自定义节点调用方便搭建更复杂的绘图工作流。增加批量优化能力一次提交多个用户需求统一调用模型合并返回。引入 A/B 测试比较不同系统和提示词模板对最终出图效果的影响用数据决定保留哪个模板。从实际项目角度看提示词优化不是一个一劳永逸的固定功能而是一个需要持续调整的服务。模型在变绘图产品在变用户需求也在变保持“输入自然语言输出结构化提示词”这条链路清晰稳定比迷信某一个模型版本更重要。建议先按照本文的结构把最小闭环跑通然后逐项加入缓存、监控和模板调优让这套链路真正服务于你的日常绘图或业务场景。
在 AI 绘图与视觉内容生成工作流里提示词一直是决定成片质量的关键但也是大多数人最容易卡住的地方。用户往往只输入“一只猫在窗台上看月亮”这样的自然语言真正下发到 MiniMax H3 这类生成模型时却需要包含主体、环境、镜头、光影、画质修饰词等结构化信息。本文围绕 MiniMax H3 提示词优化场景讲解如何用 Gemma 系列轻量模型在本地完成提示词改写再封装成 HTTP API最后通过绘世Stable Diffusion WebUI 整合包插件接入绘图流程形成一条“自然语言 - 优化提示词 - 调用生成模型”的自动化链路同时覆盖提速、缓存、并发和常见排错策略。在实际项目中提示词优化并不是简单地在原有句子上拼接几个英文标签。它需要理解用户意图、匹配目标模型的语言习惯、控制长度与权重还要考虑推理速度。如果每次写提示词都依赖远程大模型既会引入网络延迟也可能带来隐私和数据成本问题。把 Gemma 这类开源轻量模型部署在本地并做一层 API 封装就能在延迟、成本和可控性之间取得平衡。1. 提示词优化要先看数据链路而不是只看模型很多人一提到提示词优化第一反应是找更好的 Prompt 模板或者换一个更聪明的大模型。但在实际工作流里真正决定体验的是整条数据链路用户输入进入系统后经过哪些处理由谁改写改写结果给谁消费中间如何缓存和失败回退。只有先把这条链路定下来模型选择才有意义。1.1 为什么本地轻量模型适合做提示词优化提示词优化任务有一个特点输入和输出都是短文本逻辑相对简单但对延迟敏感。用户在绘图界面等一个提示词等待时间通常不能超过几秒。云端大模型虽然能力更强但网络往返和排队时间会让体验明显下降。本地轻量模型的好处是把推理放在自己机器上延迟可控离线可用也不会把用户输入发送到第三方服务。以 Gemma 系列为例它提供从几十亿到几百亿参数的不同版本经过量化后可以运行在消费级显卡上。这类模型经过微调后理解指令的能力并不弱处理“把自然语言改写成结构化绘图提示词”这种任务完全够用。标题里提到的 Gemma4 具体版本和量化格式要以实际发布的模型文件为准本地说法并不重要关键思路是用足够小、足够快的模型承担提示词优化这一环。选择本地模型时要关注三件事参数量与显存是否匹配通常 7B 到 14B 的量化模型是起步选择。上下文长度是否满足提示词模板需求至少 4K 比较稳妥。指令跟随能力是否稳定建议用同一组测试用例跑几轮确认输出格式不会飘。1.2 MiniMax H3 在链路中的位置MiniMax H3 在本文场景里作为最终消费提示词的生成模型。也就是说提示词优化服务产出的不是最终画面而是给 MiniMax H3 使用的输入指令。两者分工可以这样理解用户层输入自然语言比如“赛博朋克风格的雨夜街道霓虹灯倒影”。优化层输出结构化的 MiniMax H3 提示词比如包含主体、环境、光照、构图、风格、负面词。生成层调用MiniMax H3 收到优化后的提示词输出图片或视频。这个分工不限于具体某个模型。只要生成模型有相对固定的提示词偏好就可以在前面加一层优化服务。这样即使未来换了底层生成模型也只需要调整提示词模板不需要重写用户入口。1.3 一条完整的优化链路推荐按下面这条链路搭建用户输入自然语言 - 前端/绘图插件 - 本地提示词优化 APIGemma 模型 - 结构化提示词 - MiniMax H3 等生成模型 - 图片/视频结果链路中有两个接口要重点设计输入接口接收用户自然语言和可选参数例如风格、画幅比例、负面词。输出接口返回优化后的提示词文本同时附带解析耗时、是否命中缓存、模型名称等调试信息。这条链路跑通之后可以继续增加缓存层、模板层、失败回退层逐步变成生产可用的提示词服务。2. 环境准备先把模型和 API 服务跑起来在写代码之前先把运行环境准备好。提示词优化 API 服务本身依赖 Python 和模型推理运行时客户端则是绘世整合包里的 Stable Diffusion WebUI两者可以部署在同一台机器上也可以分开部署。2.1 依赖与模型选择推荐使用 Ollama 作为本地模型运行时。它支持 Gemma 系列模型内部处理了量化、显存管理和原生 HTTP 接口比自己用 transformers 写推理代码要省事得多。需要安装的组件包括Python 3.10 或更高版本。Ollama用于加载和管理 Gemma 模型。FastAPI 和 Uvicorn用于提供提示词优化 API 服务。绘世整合包或者任意 Stable Diffusion WebUI 环境用于验证插件调用。如果不想使用 Ollama也可以使用 llama.cpp 的 server 模式或者 Hugging Face Transformers。下面示例以 Ollama 为主因为它接口简单适合快速验证。2.2 用 Ollama 启动 Gemma 模型先确认 Ollama 安装成功ollama --version如果没有安装可以到 Ollama 官网下载对应系统版本。安装完成后拉取 Gemma 系列模型ollama pull gemma3:4b这里以 4B 量化模型为例。如果你使用的是标题中提到的“Gemma4”版本需要先确认该版本是否已经发布到模型仓库再替换模型名。如果机器显存更高比如 16GB 以上可以尝试更大的 12B 或 27B 量化版。拉取完成后启动并检查模型能否正常对话ollama run gemma3:4b 请用一句话介绍你是什么模型。看到正常回复后说明模型运行时没问题。Ollama 默认提供一个本地 HTTP 接口地址是http://localhost:11434/api/generate后续我们的 API 服务会调用这个接口。2.3 环境检查清单建议在继续前按这个清单检查一遍避免后面接口联调时反复找原因。检查项检查命令或方式通过标准Python 版本python --version3.10 或更高Ollama 服务ollama serve端口 11434 能被访问模型文件ollama list目标模型处于 available 状态显卡驱动nvidia-smi能显示显存和驱动版本绘图环境启动绘世 WebUI浏览器能打开前端页面注意学习环境只需要把链路跑通生产环境则要再考虑权限、日志、监控和回滚不能把本机启动当作部署完成。3. 实现提示词优化 API 服务这一节会写一个完整的 FastAPI 服务把本地 Gemma 模型包装成提示词优化接口。接口接收用户自然语言返回优化后的提示词并附带一些调试信息。3.1 FastAPI 服务骨架创建项目目录mkdir prompt-optimizer cd prompt-optimizer创建虚拟环境并安装依赖python -m venv .venv source .venv/bin/activate pip install fastapi uvicorn httpx pydantic在项目里创建main.py先实现服务骨架from fastapi import FastAPI from pydantic import BaseModel, Field import httpx import time app FastAPI(titleLocal Prompt Optimizer) OLLAMA_URL http://localhost:11434/api/generate MODEL_NAME gemma3:4b class OptimizeRequest(BaseModel): user_prompt: str Field(..., description用户输入的自然语言) style: str Field(, description可选风格例如 cyberpunk, realistic, anime) negative_prompt: str Field(, description可选负面词) class OptimizeResponse(BaseModel): optimized_prompt: str model: str elapsed_ms: int cached: bool False app.post(/optimize, response_modelOptimizeResponse) async def optimize_prompt(req: OptimizeRequest): start time.time() optimized await call_gemma(req) elapsed int((time.time() - start) * 1000) return OptimizeResponse( optimized_promptoptimized, modelMODEL_NAME, elapsed_mselapsed, ) async def call_gemma(req: OptimizeRequest) - str: # 下一步实现 return 这个骨架定义了两个数据模型请求参数包括user_prompt、style和negative_prompt响应体里携带了模型名和耗时。后续做缓存时cached字段会用来标记是否命中缓存。3.2 提示词优化函数call_gemma是核心函数要构造指令并调用 Ollama 接口。这里的关键不是让模型自由发挥而是通过系统提示词固定输出格式。SYSTEM_PROMPT 你是一个专业的 AI 绘图提示词优化助手。 请把用户的自然语言改写成适合 MiniMax H3 等生成模型使用的提示词。 要求 1. 使用中文描述主体、环境、光线、构图、风格。 2. 如果用户给出了风格在提示词开头说明。 3. 输出控制在 120 个中文字符以内。 4. 只输出提示词本身不要解释不要加引号。 async def call_gemma(req: OptimizeRequest) - str: user_content req.user_prompt.strip() if req.style: user_content f风格{req.style}\n用户需求{req.user_prompt} payload { model: MODEL_NAME, prompt: user_content, system: SYSTEM_PROMPT, stream: False, options: { temperature: 0.7, max_tokens: 256, }, } async with httpx.AsyncClient(timeout30) as client: resp await client.post(OLLAMA_URL, jsonpayload) resp.raise_for_status() data resp.json() text data.get(response, ).strip() return text这段代码做了三件事构造包含系统指令和用户需求的完整请求。调用 Ollama 的/api/generate接口关闭流式输出。从返回的 JSON 中取出response字段。温度设置为 0.7是平衡随机性和稳定性的常见值。如果发现输出经常跑偏可以降到 0.3 左右。max_tokens限制为 256防止模型输出过长影响下游生成。3.3 参数说明Ollama 接口中几个关键参数需要理解否则出了问题不好排查。参数含义常用值错误表现temperature采样温度越高越随机0.3 - 0.8过高时提示词结构不稳定max_tokens最大输出 token 数128 - 512过短时提示词被截断system系统提示词见示例不设置时输出格式不稳定stream是否流式返回falsetrue 时响应结构不同这里的“错误表现”不是绝对规律而是常见现象。实际项目中需要根据你自己的模型和业务反复调整。3.4 启动与验证在本机启动服务uvicorn main:app --host 0.0.0.0 --port 8100用 curl 验证接口curl -X POST http://localhost:8100/optimize \ -H Content-Type: application/json \ -d {user_prompt: 一只橘猫在窗台上看月亮, style: cinematic}正常返回示例{ optimized_prompt: 电影感画面一只橘猫坐在窗台上抬头看月亮月光洒入房间背景虚化构图居中细节丰富, model: gemma3:4b, elapsed_ms: 812, cached: false }如果这一步通过了说明 API 服务已经具备被外部插件调用的能力。接下来要做的是让绘世 WebUI 里的按钮把提示词送到这个接口。4. 在绘世 SD WebUI 中通过插件接入绘世整合包内置了 Stable Diffusion WebUI而 WebUI 自带 HTTP API 和扩展机制。这里的常见需求是用户在图生图或文生图界面写好自然语言点击一个按钮自动把优化后的提示词回填到输入框。实现方式可以是一个前端脚本扩展也可以是一个更完整的后端插件。4.1 绘世 API 与插件机制说明Stable Diffusion WebUI 的 API 接口通常以/sdapi/v1/...开头插件则放在extensions目录下。插件可以包含 Python 后端代码也可以包含 JavaScript 前端脚本。在绘世整合包里典型的插件目录结构如下extensions/ prompt-optimizer/ scripts/ main.py javascript/ prompt_optimizer.js install.py README.md由于绘世本身就是基于 Stable Diffusion WebUI 的整合包官方对扩展机制的限制比较少插件可以在 WebUI 启动时被自动加载。如果绘世版本较老可能需要手动在启动参数中开启 API。4.2 插件核心代码这里用一个最小方案通过 WebUI 的scripts目录注册脚本在文生图页面上增加一个“优化提示词”按钮点击后把当前正向提示词发送到http://localhost:8100/optimize再把返回的优化结果回填。创建extensions/prompt-optimizer/scripts/main.pyimport gradio as gr from modules import script_callbacks def optimize_and_fill(prompt): import requests import json resp requests.post( http://localhost:8100/optimize, json{user_prompt: prompt}, timeout30 ) if resp.status_code 200: data resp.json() return data.get(optimized_prompt, prompt) return prompt def on_ui_tabs(): with gr.Blocks() as demo: with gr.Row(): input_text gr.Textbox(label自然语言输入, lines4) output_text gr.Textbox(label优化结果, lines4) btn gr.Button(优化提示词) btn.click( optimize_and_fill, inputsinput_text, outputsoutput_text ) return [(demo, 提示词优化)] script_callbacks.on_ui_tabs(on_ui_tabs)这段代码注册了一个新的 Tab 页面用户可以在页面上输入自然语言点击按钮后得到优化结果。如果要回填到默认的文生图输入框需要额外调用 WebUI 的前端接口或者把优化结果复制粘贴。4.3 插件配置为了让插件适应不同环境把优化服务地址提取到配置里。可以在scripts/main.py中读取环境变量import os OPTIMIZER_URL os.getenv(PROMPT_OPTIMIZER_URL, http://localhost:8100/optimize)在绘世启动脚本中设置环境变量即可export PROMPT_OPTIMIZER_URLhttp://127.0.0.1:8100/optimize生产环境下不要写死地址建议通过配置文件或环境变量维护。4.4 验证端到端流程启动绘世 WebUI 后打开浏览器进入“提示词优化”Tab输入“一只橘猫在窗台上看月亮”点击“优化提示词”。预期结果下方输出框中出现结构化的中文提示词。提示词优化服务日志显示 200 响应。MiniMax H3 或其它生成模型能根据优化后的提示词正常出图。端到端验证完成后可以认为这条链路是可用的。但距离生产使用还有差距因为尚未考虑速度优化和异常分支。5. 提速优化量化、缓存、并发和模板标题里提到“提速”所以这一节专门讲如何让提示词优化服务更快、更省资源。提速不是单点优化而是从模型部署、请求处理、业务逻辑三个层面分别下手。5.1 用量化模型降低推理开销在 Ollama 中同一个模型往往有不同量化等级。量化等级越低显存占用越小推理速度越快但输出质量可能会有轻微下降。可以用ollama list查看模型大小也可以按需拉取不同量化版本ollama pull gemma3:4b-q4_K_M ollama pull gemma3:4b-q8_0如果你的显卡显存有限推荐从q4_K_M开始试。这个版本在大多数 4B 模型上兼顾速度和质量。显存更充裕时再尝试更大模型。在 API 服务里把模型名称做成配置避免每次修改代码MODEL_NAME os.getenv(OPTIMIZER_MODEL, gemma3:4b-q4_K_M)5.2 提示词缓存设计同一个用户需求在短时间内反复提交是很常见的。如果每次请求都调用模型浪费算力且增加延迟。可以引入内存缓存。from functools import lru_cache lru_cache(maxsize256) def cached_optimize(user_prompt: str, style: str, negative_prompt: str) - str: # 这里调用模型但只有第一次执行 return optimized result使用lru_cache的注意点是输入参数必须可哈希并且缓存只能存在单进程内。如果服务部署在多个节点要改成 Redis 等外部缓存。命中缓存后接口响应时间可以从几百毫秒降到几毫秒这是成本最低的提速手段。5.3 并发与超时设置本地模型推理时多路同时请求容易导致显存不足或队列堆积。Ollama 默认串行处理单模型请求但可以通过OLLAMA_NUM_PARALLEL环境变量控制并行数。在 API 服务这一侧需要使用asyncio.Semaphore限制并发请求数import asyncio semaphore asyncio.Semaphore(2) async def call_gemma_with_limit(req: OptimizeRequest) - str: async with semaphore: return await call_gemma(req)超时设置同样重要。如果 Ollama 卡住请求会一直占用连接。在 httpx 客户端里设置连接超时和读取超时timeout httpx.Timeout(connect5.0, read60.0, write10.0, pool5.0)并发数 2 是保守起步值具体要根据显卡显存和模型大小调整。如果把模型换成了更大的 27B 版本并发数要降到 1。5.4 针对 MiniMax H3 的提示词模板提示词优化服务的目标是让生成模型更容易理解。不同生成模型对提示词格式的偏好不同。MiniMax H3 如果更偏好中文描述优化服务就输出中文如果更偏好英文标签则需要让 Gemma 模型输出英文。可以通过系统提示词控制输出语言和结构SYSTEM_PROMPT_EN You are a prompt optimizer for image generation. Convert user input into English tags. Separate tags with commas. Do not output explanations. 建议准备多套模板通过请求参数选择模板名称适用场景输出示例中文描述式中文生成模型电影感画面一只橘猫坐在窗台上英文标签式英文提示词模型cinematic, orange cat, window, moonlight结构分句式视频生成模型主体橘猫。环境窗台。光照月光模板不是越多越好而是要对齐下游模型的偏好。这里的核心原则是提示词优化服务不追求“优美的中文”而是追求“下游模型可理解的结构”。6. 常见问题与排查路径本地服务加插件调用常见的报错集中在网络连通、模型加载、参数格式和数据解析几类。下面给出一条排查顺序和常见问题速查表。6.1 报错排查顺序当优化接口失败时按这个顺序查看绘世 WebUI 前端有没有报错。看提示词优化服务的日志有没有异常。用 curl 单独调用/optimize确认服务本身是否正常。查看 Ollama 是否在运行ollama list是否能看到模型。检查端口是否能连通curl http://localhost:11434/api/tags。检查显卡显存确认模型是否被其他程序占用。最后检查代码里的参数名和返回字段有没有拼写错误。先检查数据是否到达再检查模型是否推理最后检查结果是否被正确解析这条路径可以避免在错误层浪费时间。6.2 常见问题速查表问题现象常见原因检查方式处理建议请求返回 404绘世插件地址错误或服务未启动检查 uvicorn 启动日志修正PROMPT_OPTIMIZER_URL返回 500Ollama 未运行或模型未拉取运行ollama list启动 Ollama 并拉取模型响应很慢并发过大或模型过大查看显存占用和 CPU 使用率降低并发数使用较小量化模型输出格式不稳定系统提示词缺少格式约束查看模型原始输出增强系统提示词降低 temperature提示词被截断max_tokens设置过小查看响应字段是否完整调大max_tokens插件按钮无反应浏览器控制台报跨域或脚本错误打开开发者工具查看 Console确认插件 JS 被加载确认 API 地址可访问6.3 三个高频坑第一个坑是直接用localhost调用其他服务但绘世 WebUI 和优化服务不一定在同一台机器。如果分开部署要把地址改成实际 IP并确保防火墙放行端口。第二个坑是修改了系统提示词后发现输出结果没有变化。原因是 Ollama 可能缓存了模型上下文或者请求拼接时覆盖了系统提示词。可以在调用前显式传入system字段并确认代码里没有把系统提示词和用户输入拼接混在一起。第三个坑是把缓存看得太重导致用户改了一次风格后仍返回旧结果。用lru_cache做缓存时要保证style和negative_prompt也作为缓存 key。如果使用 Redis 做缓存还要设置过期时间避免过期结果长期占用。7. 生产环境落地建议如果只是自己本机玩前面内容已经够用。如果要把这个提示词优化服务稳定地提供给团队或线上业务还需要补上部署、监控、安全等环节。7.1 服务化部署不要把 FastAPI 服务直接暴露在公网。推荐用 Nginx 或 Caddy 做反向代理并加上访问密钥。启动命令可以参考uvicorn main:app --host 127.0.0.1 --port 8100 --workers 1注意--workers 1是因为当前进程内有lru_cache多 worker 会导致缓存各持一份并且多进程同时调用 Ollama 会增加显存压力。生产环境多实例部署时应把缓存迁到 Redis。7.2 监控与日志在 FastAPI 中添加一个简单的请求日志中间件from fastapi import Request import logging logger logging.getLogger(optimizer) app.middleware(http) async def log_requests(request: Request, call_next): start time.time() response await call_next(request) elapsed int((time.time() - start) * 1000) logger.info( path%s status%s elapsed_ms%d, request.url.path, response.status_code, elapsed, ) return response生产环境还应监控接口延迟的 P50、P95 值。Ollama 队列长度。显存占用率。缓存命中率。这些指标能帮助你判断何时该扩容、何时该换模型。7.3 发布前检查清单在发布前按这个清单逐项确认检查项完成标准配置外置API 地址、模型名称、并发数不写死在代码中异常处理模型调用失败时有兜底提示词不让用户拿到空结果超时设置上游调用和下游调用都有明确超时缓存策略缓存 key 包含风格和负面词有有效期日志输出关键请求有耗时、状态码和错误信息权限控制内部 API 增加令牌校验回滚方案保留上一个可用的模型版本和配置文件7.4 扩展方向这条链路跑通后可以继续做三件事将提示词优化服务接入 ComfyUI通过自定义节点调用方便搭建更复杂的绘图工作流。增加批量优化能力一次提交多个用户需求统一调用模型合并返回。引入 A/B 测试比较不同系统和提示词模板对最终出图效果的影响用数据决定保留哪个模板。从实际项目角度看提示词优化不是一个一劳永逸的固定功能而是一个需要持续调整的服务。模型在变绘图产品在变用户需求也在变保持“输入自然语言输出结构化提示词”这条链路清晰稳定比迷信某一个模型版本更重要。建议先按照本文的结构把最小闭环跑通然后逐项加入缓存、监控和模板调优让这套链路真正服务于你的日常绘图或业务场景。
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
