1. 为什么大模型画图总翻车从 AntV MCP Server Chart 说起大模型写 SQL 很溜但让它直接吐出一张能看的图表十次有八次是灾难。我见过太多团队卡在这一步模型把数据算对了却给你返回一段残缺的 ECharts 配置或者干脆画出一张坐标轴全是英文、图例重叠、颜色辣眼睛的图。问题不在模型笨而在于生成图表这件事本身需要一套结构化的渲染能力光靠 Prompt 硬编是不稳定的。AntV MCP Server Chart 解决的正是这个断层。它把 AntV 的图表渲染能力封装成符合 Model Context Protocol 的工具大模型通过标准协议调用工具而不是自己拼前端代码。你可以把它理解成模型负责想清楚要画什么图、数据长什么样AntV 负责把图渲染得专业好看中间用 MCP 协议对接。这样职责分离稳定性立刻上一个台阶。这套方案适合谁三类人最受益。第一类是做 Text2SQL 或 BI 问答的开发者用户问上个月订单趋势你希望直接返回一张折线图而不是一堆数字第二类是做智能体编排的团队需要在 Agent 流程里插入可视化节点第三类是没有前端背景的后端或算法同学不想学 D3、ECharts 语法只想让模型把图生成出来。整条链路的核心检索词就是 AntV MCP Server Chart 与大模型结合构建可视化智能体。完整链路分四段MCP Server 配置、图表生成工具接入、大模型生成 SQL 与推荐图表类型、智能体编排调用。下面我会把每一段都拆成可复制的配置和代码你跟着做就能跑通。在动手之前先说清楚一个前提MCP Server Chart 默认会调用公网渲染服务如果你在企业内网或对数据安全有要求需要做私有化部署把渲染请求转发到自己的服务。这一点我在第三节会给出完整配置。另外模型侧我建议用支持工具调用Function Calling的模型否则 MCP 工具没法被正确触发。2. TaoToken 前置准备给智能体接上稳定的大模型底座可视化智能体的大脑是大模型它要完成两件关键事根据表结构生成 SQL以及根据查询结果推荐图表类型。这两步都依赖模型的推理和工具调用能力。所以第一步不是急着配 MCP而是先把模型接入搞定。我推荐用 TaoToken 作为模型接入层原因是它同时提供 OpenAI 兼容的 API 和 Claude Code 的接入方式无论你用 LangChain、LangGraph 还是直接写 HTTP 请求都能对上。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时别写错。接入前你需要准备三样东西我把它叫做三件套Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api API Key 在控制台的 API Keys 页面生成Model ID 根据你选的模型填比如 qwen-plus、claude 系列等。这三件套在后面所有配置里都会反复出现建议先记下来。生成 Key 的入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。进去之后创建一个新 Key复制保存页面关闭后就看不到了。如果你只是想先验证模型能不能正常对话可以用模型对话页面快速测一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。对于长期做编码和 Agent 编排的场景Coding Plan 会更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合需要频繁调用模型、跑长流程智能体的开发者。如果你用的是 Claude Code 做开发接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 专用接入页在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。配置环境变量时我习惯统一命名避免后面代码里到处硬编码。你可以这样写export MODEL_BASE_URLhttps://taotoken.net/api export MODEL_API_KEYsk-你的key export MODEL_NAMEqwen-plus export MODEL_TEMPERATURE0.75这里有个坑要提醒Base URL 结尾不要多加/v1很多 OpenAI 兼容库会自动补路径你手动加了反而会 404。另外 API Key 不要提交到 Git用.env文件管理记得加进.gitignore。模型接入验证很简单用 curl 打一个 chat 请求curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $MODEL_API_KEY \ -H Content-Type: application/json \ -d { model: qwen-plus, messages: [{role: user, content: 用一句话说明折线图适合什么场景}] }如果返回里有正常的choices[0].message.content说明模型侧通了。这一步没通之前别往下配 MCP否则报错你分不清是模型问题还是工具问题。3. 可复制配置AntV MCP Server Chart 接入与私有化渲染这一节是全文的核心我会给出完整的 MCP Server 配置片段。先说整体架构大模型通过 MCP 协议调用 AntV 图表工具AntV 工具把渲染请求发到一个渲染服务渲染服务生成图片并返回 URL。默认情况下渲染服务是公网的我们要把它换成自己的这就是私有化部署的意义。先配 MCP Server。如果你用 Claude Code 或支持 MCP 的客户端配置文件通常长这样注意路径和字段名要和你的客户端一致{ mcpServers: { mcp-server-chart: { command: npx, args: [-y, antv/mcp-server-chart], env: { VIS_REQUEST_SERVER: http://host.docker.internal:3100/generate } } } }这里的VIS_REQUEST_SERVER是关键它把图表渲染请求指向你自己的服务。如果你不做私有化删掉这个 env工具会走默认公网服务。但生产环境我强烈建议私有化数据不出内网。接下来配渲染服务。我用一个轻量的 GPT-VIS-API 做渲染层它接收结构化数据调用 AntV 渲染把图片存到对象存储返回带签名的 URL。先起一个 MinIO 做图片存储docker run -d \ --name minio \ -p 19000:9000 \ -p 19001:9001 \ -v $(pwd)/volume/minio/data:/data \ -e MINIO_ROOT_USERadmin \ -e MINIO_ROOT_PASSWORD12345678 \ minio/minio:RELEASE.2025-04-22T22-12-26Z \ server /data --console-address :9001起来之后访问http://localhost:19001用 admin / 12345678 登录创建一个名为chart-images的 Bucket权限设为 public 可读然后生成 Access Key 和 Secret Key后面渲染服务要用。再起渲染服务docker run -d \ --name gpt-vis-api \ -p 3100:3000 \ --add-host host.docker.internal:host-gateway \ -e MINIO_ENDPOINThost.docker.internal \ -e MINIO_PORT19000 \ -e MINIO_USE_SSLfalse \ -e MINIO_ACCESS_KEYyour-access-key \ -e MINIO_SECRET_KEYyour-secret-key \ -e MINIO_BUCKETchart-images \ -e MINIO_PUBLIC_DOMAINhttp://localhost:19000 \ crpi-7xkxsdc0iki61l0q.cn-hangzhou.personal.cr.aliyuncs.com/apconw/gpt-vis-api:0.0.1注意host.docker.internal在 Linux 上需要--add-host才能解析生产环境要换成真实服务器 IP。渲染服务起来后用一条 curl 验证curl -X POST http://localhost:3100/generate \ -H Content-Type: application/json \ -d { type: line, data: [ {time: 2025-05, value: 512}, {time: 2025-06, value: 1024} ] }成功的话会返回类似{url: http://localhost:19000/chart-images/chart-abc123.png?Expires...}的结果。拿到这个 URL 就说明渲染链路通了。最后把 MCP Server 和渲染服务串起来。MCP Server 的VIS_REQUEST_SERVER指向http://host.docker.internal:3100/generate这样模型调用图表工具时请求会转发到你的渲染服务图片存进你的 MinIO返回你自己的 URL。整条链路的数据都在你掌控之内。如果你用 Cline 或 CC Switch 管理 MCP配置方式类似核心还是三件套Base URL、Key、Model ID 要填对MCP Server 的 command 和 env 要匹配。Cline 的 MCP 配置里command填npxargs填[-y, antv/mcp-server-chart]env 里加VIS_REQUEST_SERVER。Codex 用户如果走auth.json把模型凭证写进去MCP 部分单独配。4. 验证请求让大模型生成 SQL 并渲染出图表配置通了接下来验证智能体能不能真的从自然语言到图表。这一步分两个子任务模型生成 SQL 和推荐图表类型然后 Agent 调用 MCP 工具渲染。先设计 Prompt。核心是让模型输出纯 JSON包含sql_query和chart_type两个字段。chart_type要从 AntV 支持的图表类型里选比如generate_line_chart、generate_bar_chart、generate_pie_chart等。Prompt 里要把表结构、表关系、当前时间都传进去约束模型不许瞎编列名。import json from datetime import datetime from langchain.prompts import ChatPromptTemplate def sql_generate(state): llm get_llm() prompt ChatPromptTemplate.from_template( 你是专业 DBA根据表结构和用户问题生成 MySQL 查询并推荐图表类型。 ## 约束 1. 只输出一条可执行 SQL不含解释和 Markdown。 2. 只能使用提供的表和列。 3. 输出纯 JSON{{sql_query: ..., chart_type: ...}} ## 信息 表结构{db_schema} 表关系{table_relationship} 用户提问{user_query} 当前时间{current_time} ## 图表类型 - generate_line_chart: 时间趋势 - generate_bar_chart: 分类对比 - generate_pie_chart: 占比 - generate_area_chart: 累积趋势 ) chain prompt | llm response chain.invoke({ db_schema: state[db_info], user_query: state[user_query], table_relationship: state.get(table_relationship, []), current_time: datetime.now().strftime(%Y-%m-%d %H:%M:%S), }) clean response.content.strip().removeprefix(json).strip().removesuffix().strip() parsed json.loads(clean) state[generated_sql] parsed[sql_query] state[chart_type] mcp-server-chart- parsed[chart_type] return state注意chart_type前面加了mcp-server-chart-前缀这是因为 MCP Hub 注册工具时会加命名空间实际工具名是mcp-server-chart-generate_line_chart。不加前缀会找不到工具。然后写渲染 Agent。用 LangGraph 的create_react_agent动态过滤工具只加载当前需要的图表工具减少 Token 消耗和幻觉import os from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent async def data_render_ant(state): client MultiServerMCPClient({ mcphub-sse: { url: os.getenv(MCP_HUB_DATABASE_QA_GROUP_URL), transport: streamable_http, } }) chart_type state[chart_type] tools await client.get_tools() tools [t for t in tools if t.name chart_type] llm ChatOpenAI( modelos.getenv(MODEL_NAME, qwen-plus), temperaturefloat(os.getenv(MODEL_TEMPERATURE, 0.75)), base_urlos.getenv(MODEL_BASE_URL), api_keyos.getenv(MODEL_API_KEY), streamingTrue, ) chart_agent create_react_agent( modelllm, toolstools, promptf你是 BI 专家根据数据渲染图表。 输入数据{state[execution_result]} 要求x 轴和 y 轴标签用中文返回图表链接。, ) result await chart_agent.ainvoke( {messages: [(user, 根据输入数据渲染图表)]}, config{configurable: {thread_id: chart-render}}, ) state[chart_url] result[messages][-1].content return state跑通之后你输入上个月每天的订单量趋势模型会生成类似SELECT DATE(created_at) AS day, COUNT(*) AS orders FROM orders GROUP BY day ORDER BY day的 SQL推荐generate_line_chartAgent 调用 MCP 工具最终返回一个图片 URL。打开 URL 就是一张 AntV 渲染的折线图坐标轴中文样式专业。验证成功的标志有三个SQL 能执行、图表类型合理、返回的 URL 能打开。三个都满足说明整条链路通了。5. 常见报错排查401、local proxy failed 与 reading choices配 MCP 和智能体的过程中报错集中在几个地方。我把踩过的坑列出来对照着查能省不少时间。401 Unauthorized。这个最常见八成是 API Key 或 Base URL 配错。先检查MODEL_API_KEY有没有多余空格再确认MODEL_BASE_URL是不是https://taotoken.net/api结尾别加/v1。如果用的是 Claude Code 接入检查auth.json里的凭证格式对不对。还有一种情况是 Key 过期或被删去控制台重新生成一个。local proxy failed。这个报错通常出现在 MCP Server 启动阶段说明 MCP 客户端连不上工具进程。检查npx -y antv/mcp-server-chart能不能在终端单独跑起来如果卡住或报网络错误换 NPM 源npm config set registry https://registry.npmmirror.com。如果是 Docker 里跑检查host.docker.internal能不能解析Linux 上要加--add-host host.docker.internal:host-gateway。reading choices of undefined。这是模型返回结构不对代码里取response.choices[0]时choices是 undefined。原因通常是请求没成功返回的是错误对象。打印完整 response 看error字段多半是模型名写错或额度不足。还有一种可能是流式和非流式混用streamingTrue时返回的是迭代器不能直接取choices。OAuth 相关报错。如果你用 Claude Code 接入可能会遇到 OAuth 认证失败。检查接入文档里的回调地址和凭证配置Claude Code 专用页有详细说明。别把 OAuth 和 API Key 两种方式混用选一种配到底。图表工具找不到。报错tool not found或mcp-server-chart-xxx不存在。检查 MCP Hub 里工具是否注册成功工具名前缀是不是mcp-server-chart-。如果用了动态过滤确认chart_type和实际工具名完全一致大小写敏感。渲染返回 500。渲染服务报错先看gpt-vis-api的日志。常见原因是 MinIO 连不上检查MINIO_ENDPOINT和端口Docker 网络里localhost指向容器自己要用host.docker.internal或真实 IP。还有可能是 Bucket 权限没设 public图片存进去了但 URL 访问不了。排查顺序建议先验证模型侧 curl 通不通再验证渲染服务 curl 通不通最后验证 MCP 工具能不能被调用。分段隔离别一上来就怀疑智能体逻辑。6. 长期编码与 Agent 编排把可视化能力沉淀下来跑通单次图表生成只是开始真正有价值的是把它沉淀成可复用的能力。如果你在做长期的编码和 Agent 编排建议把模型接入统一到 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 这样频繁调用模型时成本和稳定性都更可控。工程化上我建议做三件事。第一把 SQL 生成和图表渲染拆成两个独立的 Agent 节点中间用状态传递方便单独调试和替换。第二图表类型推荐不要只靠模型可以加一层规则兜底比如时间字段优先折线图、分类字段优先柱状图模型推荐和规则冲突时以规则为准。第三渲染服务加缓存相同数据和图表类型直接返回已有 URL省渲染开销。MCP 工具的动态加载也很关键。AntV 支持 25 种以上图表类型全量加载会撑爆上下文还容易让模型选错工具。按需加载当前需要的工具Token 消耗能降一大截幻觉也少。我实测下来动态过滤后工具调用准确率明显提升。如果你要把这套能力接到自己的产品里API Keys 和接入文档是必看的API Keys 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有完整的参数说明和示例比到处搜零散教程靠谱。最后说个实用技巧图表渲染的 Prompt 里一定要强制中文标签。模型默认可能给你英文的 x 轴、y 轴用户看着别扭。在 Prompt 里明确写x 轴和 y 轴标签必须使用中文再配合渲染服务的默认配置出来的图才像样。这个细节不起眼但直接影响最终交付质量。