企业官网建设流程全解析

1. 从论文到工程：Qwen-VL 三类任务到底怎么接

Qwen-VL 是通义千问系列的视觉语言大模型，能做的事可以粗暴拆成三类：看图说话（理解）、按描述框出目标（视觉定位）、把图里的文字读出来（文本阅读）。论文里它靠位置感知的 VL Adapter 和三阶段训练把这三件事塞进同一个模型，但落到工程里，你真正要关心的不是 9.6B 参数怎么分布，而是：一次请求怎么发、图片怎么传、坐标怎么解析、返回的框怎么用。

我见过太多人卡在第一步——不是模型不会，是请求格式没对齐。Qwen-VL 的边界框输出是归一化到 [0,1000) 的字符串，格式固定为(X_topleft,Y_topleft),(X_bottomright,Y_bottomright)，外面包<box></box>，对应的文本描述包<ref></ref>。如果你拿到的返回里没有这些标记，八成是 prompt 没写对，或者模型版本选错了。

这篇不重复论文的评测表格，而是把理解、定位、文本阅读三条链路拆成可复制的请求骨架。你跟着走一遍，能在 TaoToken 的统一 Key/API 通道下完成一次端到端跑通，拿到真实的坐标和文字结果。适合谁：正在做多模态应用、需要把图片理解接进自己系统、又不想在多个平台之间来回切 Key 的开发者。

2. TaoToken 前置：一把 Key 打通多模态调用

TaoToken 在这里的角色是统一入口。你不需要为 Qwen-VL 单独注册一个平台、单独管一套额度，而是用同一个 Key 走同一个 API 地址，模型名切换即可。对多模态场景尤其省事——理解、定位、OCR 三类任务往往要对比不同模型的表现，统一通道意味着你只维护一份配置。

先拿 Key。打开 https://taotoken.net/api-keys ，登录后创建一个 API Key，复制出来。注意这个 Key 只在创建时完整显示一次，丢了就重新建。

拿到 Key 之后，你的请求基地址是：

https://taotoken.net/api

不要在这个地址后面加 UTM 参数，API 调用保持干净。模型名按你实际要用的 Qwen-VL 版本填，比如qwen-vl-plus或qwen-vl-max，具体以控制台模型列表为准。控制台入口在 https://taotoken.net/console ，里面能看到可用模型和额度消耗。

如果你打算长期跑编码类或 Agent 类任务，顺带看一眼 Coding Plan：https://taotoken.net/coding-plan ，它和按量调用是两条线，别混着算。

注意：Key 不要写死在代码里提交到仓库。用环境变量或本地配置文件，下面会给 settings.json 示例。

3. 可复制配置：settings.json 与请求骨架

先给一份最小可用的 settings.json，放在项目根目录或你习惯的配置目录：

{ "taotoken": { "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key", "default_model": "qwen-vl-plus", "timeout": 60 }, "qwen_vl": { "model_understanding": "qwen-vl-plus", "model_grounding": "qwen-vl-max", "model_ocr": "qwen-vl-max", "max_tokens": 1024 } }

理解任务用 plus 就够，定位和 OCR 对细粒度要求高，建议上 max。这不是硬规定，你可以按实测效果调。

请求骨架用 Python 写，依赖 openai 兼容客户端即可，因为 TaoToken 的接口是 OpenAI 兼容格式：

import json import base64 from openai import OpenAI with open("settings.json", "r", encoding="utf-8") as f: cfg = json.load(f) client = OpenAI( api_key=cfg["taotoken"]["api_key"], base_url=cfg["taotoken"]["base_url"] ) def encode_image(path): with open(path, "rb") as f: return base64.b64encode(f.read()).decode("utf-8") def ask_qwen_vl(image_path, prompt, model=None): model = model or cfg["qwen_vl"]["model_understanding"] b64 = encode_image(image_path) resp = client.chat.completions.create( model=model, messages=[ { "role": "user", "content": [ {"type": "text", "text": prompt}, { "type": "image_url", "image_url": { "url": f"data:image/jpeg;base64,{b64}" } } ] } ], max_tokens=cfg["qwen_vl"]["max_tokens"] ) return resp.choices[0].message.content

这段代码的关键点：图片走 base64 内联，格式是data:image/jpeg;base64,前缀加编码串。如果你用图片 URL，把image_url.url换成公网可访问的链接也行，但内联更稳，不依赖外部图床。

三类任务的 prompt 写法不同，下面分开说。

3.1 理解任务：让模型描述和推理

理解任务最简单，prompt 直接问就行：

result = ask_qwen_vl( "test.jpg", "请描述这张图片的内容，并指出画面中的人物在做什么。" ) print(result)

返回是自然语言描述。如果你要结构化输出，在 prompt 里明确要求 JSON：

result = ask_qwen_vl( "test.jpg", "用 JSON 返回：{\"scene\": \"场景描述\", \"objects\": [\"物体1\", \"物体2\"], \"action\": \"动作\"}" )

模型不保证 100% 合法 JSON，拿到后做一次json.loads兜底，失败就重试或降级成文本解析。

3.2 视觉定位：拿到归一化坐标

定位任务的 prompt 必须明确要求输出<box>格式，否则模型可能只给你文字描述：

result = ask_qwen_vl( "street.jpg", "请定位图中的红色汽车，输出格式为 <box>(x1,y1),(x2,y2)</box>，坐标归一化到 0-1000。", model=cfg["qwen_vl"]["model_grounding"] ) print(result)

典型返回长这样：

<box>(112,340),(580,720)</box>

解析时用正则提取：

import re def parse_box(text): m = re.search(r"<box>\((\d+),(\d+)\),\((\d+),(\d+)\)</box>", text) if not m: return None x1, y1, x2, y2 = map(int, m.groups()) return {"x1": x1, "y1": y1, "x2": x2, "y2": y2}

拿到归一化坐标后，乘以原图宽高再除以 1000，就是像素坐标。这一步别忘，否则画框会偏。

3.3 文本阅读：OCR 与文档理解

文本阅读的 prompt 要指定输出格式，比如逐行返回：

result = ask_qwen_vl( "receipt.jpg", "请读取图中所有文字，按行输出，每行一条，不要添加额外解释。", model=cfg["qwen_vl"]["model_ocr"] ) print(result)

如果是表格或票据，可以要求结构化：

result = ask_qwen_vl( "invoice.jpg", "提取图中的发票信息，用 JSON 返回：{\"invoice_no\": \"\", \"date\": \"\", \"amount\": \"\", \"items\": []}" )

OCR 场景对图片分辨率敏感。Qwen-VL 训练时第二阶段用了 448x448，实际调用时图片太小会丢字，太大又增加 token 消耗。建议长边控制在 1600 像素以内，先压缩再传。

4. 验证请求：一次端到端跑通

配置写完，跑一个最小验证脚本，确认 Key、地址、模型名、图片编码四件事都对：

if __name__ == "__main__": out = ask_qwen_vl( "test.jpg", "这张图里有什么？用一句话回答。" ) print("理解结果:", out) box_out = ask_qwen_vl( "test.jpg", "定位图中最主要的物体，输出 <box>(x1,y1),(x2,y2)</box>。", model=cfg["qwen_vl"]["model_grounding"] ) print("定位结果:", box_out) print("解析坐标:", parse_box(box_out))

成功的话你会看到类似输出：

理解结果: 图片中有一只橘猫坐在窗台上，窗外是绿树。 定位结果: <box>(210,180),(760,890)</box> 解析坐标: {'x1': 210, 'y1': 180, 'x2': 760, 'y2': 890}

如果定位返回里没有<box>，先别怀疑模型，检查 prompt 是否明确写了输出格式。Qwen-VL 对格式指令的跟随能力不错，但你不说它就不给。

验证通过后，把parse_box的结果映射回原图，用 PIL 画个矩形存下来，肉眼确认框的位置对不对：

from PIL import Image, ImageDraw img = Image.open("test.jpg") w, h = img.size box = parse_box(box_out) if box: draw = ImageDraw.Draw(img) draw.rectangle( [box["x1"] * w / 1000, box["y1"] * h / 1000, box["x2"] * w / 1000, box["y2"] * h / 1000], outline="red", width=3 ) img.save("boxed.jpg")

打开boxed.jpg，框准了就说明整条链路通了。

5. 本篇常见错排查

报 401 或 invalid api key：Key 复制错了，或者 settings.json 里还留着占位符。重新去 https://taotoken.net/api-keys 建一个，确认没有多余空格。

报 model not found：模型名写错。去 https://taotoken.net/console 看可用列表，别凭记忆填。

图片传了但模型说看不到：base64 前缀漏了data:image/jpeg;base64,，或者图片本身损坏。先用小图测试，排除编码问题。

定位坐标全是 0 或超出 1000：prompt 没要求归一化，模型按像素输出了。明确写「坐标归一化到 0-1000」。

OCR 漏字：图片分辨率太低或压缩过度。长边提到 1200 以上再试，同时确认 prompt 要求了逐行输出。

返回被截断：max_tokens太小。OCR 长文档场景调到 2048 或更高。

超时：大图 base64 后请求体很大，网络慢会超时。把 timeout 设到 60 秒以上，或者改用图片 URL 方式。

接入文档在 https://taotoken.net/doc ，里面有完整的参数说明和错误码对照，遇到没列出的报错先去那里查。

6. 下一步：按场景选通道

三类任务跑通后，你会发现理解任务调用最频繁、定位和 OCR 对模型版本更敏感。如果你只是偶尔验证模型效果，直接用模型对话页试 prompt 最快：https://taotoken.net/model-chat 。

如果你要把 Qwen-VL 接进自动化流程、批量处理图片，或者和编码 Agent 配合做多模态任务，建议走 Coding Plan：https://taotoken.net/coding-plan ，额度和调用方式更适合长期跑。

Key 管理和接入配置都在 https://taotoken.net/api-keys 和 https://taotoken.net/doc ，先把这两页存下来，后面调参和排障都用得上。