1. 为什么要在本地折腾 Qwen3 + MCP 图像助手
Qwen3 是通义千问团队开源的新一代大模型系列，原生支持工具调用与 MCP（Model Context Protocol）协议，这意味着它不只是聊天，还能主动去调用外部工具完成具体任务。MCP 可以理解成给 AI 装了一个"标准插座"，任何符合协议的工具服务都能插上去被模型调用，图像生成、文件读写、网页抓取都能接。Ollama 负责在本地把 Qwen3 跑起来，不花一分钱推理费用；Streamlit 负责把命令行里的能力包装成一个能点能输入的网页界面。
这套组合适合谁？适合想零成本拥有一个私有 AI 绘图助手、又不想被各种云服务额度卡脖子的开发者。你本地有台能跑 8B 模型的机器（16G 内存起步比较稳），就能把整条链路跑通。整条链路是：Streamlit 收指令 → Qwen_Agent 调度 → Qwen3 判断要不要调工具 → MCP 服务执行图像生成 → 结果回传渲染。下面我把 config.toml、settings.json 骨架、MCP 注册、启动命令和一次真实生成验证都拆开讲，最后说清楚怎么用 TaoToken 统一管理 Key 和 API 通道。
2. 前置准备：Ollama 拉模型与 TaoToken 通道
2.1 本地把 Qwen3 跑起来
先装 Ollama，各平台命令不一样，按你的系统选：
# Linux curl -fsSL https://ollama.com/install.sh | sh # macOS（也可直接下 dmg） brew install ollama # Windows 直接去官网下 OllamaSetup.exe 安装装完拉模型。8B 版本对显存和内存友好，是本地首选：
ollama run qwen3:8b第一次运行会下载约 5GB 权重，下完会进入交互界面，随便问一句能回就说明服务正常。Ollama 默认在http://localhost:11434提供 OpenAI 兼容接口，路径是/v1，这就是后面 Qwen_Agent 要连的地址。
2.2 TaoToken 统一 Key 与 API 通道
本地 Ollama 负责推理，但工具调用链路里往往还要接一些云端能力（比如更稳的图像生成、备用模型兜底）。如果每个服务单独配 Key，管理起来很乱。TaoToken 的作用就是把这些调用收敛到一个统一入口，用一套 Key 走 API 通道。
先去控制台建 Key：
- 控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console
- API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys
API 基础地址是https://taotoken.net/api（这个地址不加 UTM 参数，直接填进配置）。拿到 Key 后先存到环境变量，别硬编码进代码：
export TAOTOKEN_API_KEY="sk-你的key"注意：本地 Ollama 的
api_key填EMPTY就行，TaoToken 的 Key 是给需要走统一通道的调用用的，两者不要混。
3. 可复制配置：config.toml 与 settings.json 骨架
3.1 config.toml
Qwen_Agent 支持用配置文件管理模型和工具，放在项目根目录：
[llm] model = "qwen3:8b" model_server = "http://localhost:11434/v1" api_key = "EMPTY" generate_cfg = { top_p = 0.8, temperature = 0.7 } [llm.fallback] # 本地模型不可用或需要更强能力时，走 TaoToken 统一通道 model = "qwen3-8b" model_server = "https://taotoken.net/api/v1" api_key = "${TAOTOKEN_API_KEY}" [mcp.pollinations] command = "npx" args = ["-y", "@pollinations/model-context-protocol"]3.2 settings.json
如果你用支持 MCP 的客户端或想让配置更通用，用 JSON 骨架：
{ "mcpServers": { "pollinations": { "command": "npx", "args": ["-y", "@pollinations/model-context-protocol"], "env": {} } }, "llm": { "provider": "ollama", "base_url": "http://localhost:11434/v1", "model": "qwen3:8b" } }这两个文件的分工：config.toml给 Qwen_Agent 读，settings.json给通用 MCP 客户端读。你只跑 Streamlit 的话，config.toml是必须的，settings.json可以先留着备用。
3.3 装依赖
conda create -n qwen_agent python=3.11 -y conda activate qwen_agent pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]" pip install streamlitmcp这个 extra 一定要带上，否则 MCP 服务注册会失败。
4. MCP 服务注册与 Streamlit 应用
4.1 MCP 服务注册步骤
MCP 服务注册的核心是告诉 Qwen_Agent：启动哪个命令、传什么参数。在代码里就是function_list里的mcpServers块。注册 Pollinations 图像生成服务：
tools = [ { "mcpServers": { "pollinations": { "command": "npx", "args": ["-y", "@pollinations/model-context-protocol"] } } }, "code_interpreter", ]Qwen_Agent 会在需要时自动执行npx拉起这个 MCP 服务进程，用完回收。你不需要手动npx启动，注册进去就行。第一次运行会下载 npm 包，稍等几秒。
4.2 完整 Streamlit 应用
把下面代码存成qwen_mcp_app.py：
import streamlit as st from qwen_agent.agents import Assistant llm_cfg = { "model": "qwen3:8b", "model_server": "http://localhost:11434/v1", "api_key": "EMPTY", "generate_cfg": {"top_p": 0.8}, } tools = [ { "mcpServers": { "pollinations": { "command": "npx", "args": ["-y", "@pollinations/model-context-protocol"], } } }, "code_interpreter", ] bot = Assistant(llm=llm_cfg, function_list=tools) st.set_page_config(page_title="Qwen AI 图像助手", layout="wide") st.title("Qwen3 图像生成助手（Ollama + MCP 驱动）") st.caption("本地推理，MCP 调工具，零成本出图。") if "messages" not in st.session_state: st.session_state["messages"] = [] for message in st.session_state["messages"]: with st.chat_message(message["role"]): st.markdown(message["content"]) user_input = st.chat_input("输入指令，例如：画一只戴宇航员头盔的猫") if user_input: st.session_state["messages"].append({"role": "user", "content": user_input}) with st.chat_message("user"): st.markdown(user_input) with st.chat_message("assistant"): placeholder = st.empty() full_response = "" with st.spinner("思考中..."): try: responses = bot.run(messages=st.session_state["messages"]) for chunk in responses: pass final = [ m for m in chunk if m["role"] == "assistant" and m not in st.session_state["messages"] ] if final: full_response = "\n".join( str(r["content"]) for r in final if "content" in r ) placeholder.markdown(full_response) st.session_state["messages"].extend(final) else: placeholder.markdown("暂时没有回复。") except Exception as e: st.error(f"请求出错: {e}") st.session_state["messages"].append( {"role": "assistant", "content": f"出错: {e}"} )4.3 启动命令
streamlit run qwen_mcp_app.py浏览器会自动打开http://localhost:8501，看到聊天界面就说明 UI 起来了。
5. 验证请求：一次真实图像生成
在输入框里敲一句英文指令，比如：
Draw a cat wearing an astronaut helmet, digital art为什么建议用英文？实测下来 Pollinations 对中文指令的理解不如英文稳，英文出图质量明显更好。发送后你会看到：
- 界面显示"思考中"，Qwen3 在判断这是不是需要调工具的任务；
- 模型决定调用
pollinations的生成接口，MCP 服务被拉起； - 返回一个图片 URL，Streamlit 渲染出来。
如果返回的是图片链接而不是直接显示图，可以在代码里加一层渲染：
if "http" in full_response and (".png" in full_response or ".jpg" in full_response): st.image(full_response.strip())验证成功的标志：输入指令后 10 到 30 秒内（取决于本地机器和网络）能看到一张生成的图。如果只返回文字描述没出图，说明模型没触发工具调用，检查function_list里 MCP 块是否写对。
6. 本篇常见错排查
报错一：Connection refused连不上 11434。Ollama 服务没起。跑ollama serve或确认ollama run qwen3:8b至少成功过一次，服务才会常驻。
报错二：MCP 服务启动失败，提示npx: command not found。没装 Node.js。装个 LTS 版本，npx随 Node 一起来。
报错三：模型不调工具，只回文字。两个原因：一是 Qwen3 对工具调用的触发需要指令足够明确，把"画一只猫"改成"用图像生成工具画一只猫"；二是function_list里 MCP 配置格式写错，对照第 4.1 节检查缩进和 key 名。
报错四：中文指令出图效果差。这是 Pollinations 服务本身的限制，不是你的配置问题。把 prompt 翻成英文再发，或者让 Qwen3 先帮你把中文翻译成英文 prompt 再调工具。
报错五：TaoToken 通道调用 401。Key 没读到。确认TAOTOKEN_API_KEY环境变量在当前 shell 生效，echo $TAOTOKEN_API_KEY能打印出来。Key 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys 重新生成一个也行。
报错六：Streamlit 端口被占。换端口：streamlit run qwen_mcp_app.py --server.port 8502。
7. 后续怎么用：通道管理与能力扩展
跑通之后，日常使用就是streamlit run一条命令。如果你想让这个助手在本地模型忙不过来时自动切到云端，把config.toml里的[llm.fallback]配上 TaoToken 通道即可，Key 统一在控制台管理，不用每个服务单独维护。
想验证模型本身的能力边界，可以直接用模型对话入口试：
- 模型对话：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model-chat
如果你打算把这个助手往长期编码、Agent 自动化方向做，比如让它接更多 MCP 工具、跑定时任务，可以看 Coding Plan：
- Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan
接入细节和参数说明都在文档里：
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc
我自己的用法是：本地 Qwen3 处理日常出图和简单对话，遇到复杂 prompt 优化或需要更强模型兜底时，切到 TaoToken 通道，Key 一套走天下，省得来回换配置。
