企业官网建设流程全解析

DeepSeek 视觉 API 上线那天的消息一出来，我脑子里跳出来的第一个场景就是：以后让 Agent 去处理截图、图表、产品图片，终于不用再拐弯抹角了。标题里三个关键词——DeepSeek、视觉 API、Agent——本质上指向同一个需求。现在的 LLM Agent 已经能写代码、调工具、操作浏览器，但一旦输入变成 PNG、JPG、扫描件，大多数方案还是要绕路：要么先 OCR 抽文字，要么让另一个模型把图片转成描述文字，链路一长，错误和成本都跟着涨。单张图 0.001 元这个定价，直接把视觉能力从"偶尔用一次的昂贵功能"拉到了"Agent 日常流程里的基础组件"。这篇文章写给正在做 Agent 开发的工程师、想把多模态能力集成进自动化流程的团队，也适合刚接触 API 调用、想低成本验证图像识别效果的新手。我把这几天实际测试的配置过程、代码写法、踩过的坑和成本估算思路都整理在下面，可以直接照着抄。

1. 为什么 Agent 群体集体需要"眼睛"

先聊一个有点扎心的事实：没有视觉能力之前，Agent 处理图片的方式基本是"假装看得见"。不是开发者不想做，而是成本和技术链路双重限制，导致大多数人选择了凑合方案。

1.1 没有视觉 API 时，Agent 是怎么"看"图的

细数一下过去常见的三种路数。

第一种是纯 OCR 方案。把图片丢给 OCR 引擎抽取文本，Agent 拿到的只有一堆文字，而且往往带着识别错字。适合处理身份证、发票这类版式固定的文档，但一旦碰到带格式的表格截图、图表趋势、UI 界面，OCR 就彻底抓瞎——文字能抽出来，排版结构、颜色状态、坐标位置全丢了。

第二种是把图片交给多模态模型转述。流程是：Agent 收到图片，先调用一次大模型的 vision 能力生成一段文字描述，再把这段描述塞回给主 Agent 的上下文。这个方案的问题在于转述必然会丢失信息。让模型描述一张折线图的趋势，它可能说"整体上升"，但具体最高点出现在哪个时间点、哪个区间波动最大，这些细节经常被模糊掉。而且每次转述都是一次额外的模型调用，成本和延迟都不可忽视。

第三种更原始，直接让用户手动填写。比如 Agent 在流程中需要读取一张截图里的验证码，或者需要用户上传图片并解释内容，干脆弹一个表单让用户自己打几个字。体验上仿佛退回了十年前的网页交互，Agent 自动化流程在这里被迫中断。

这三种方案共性的痛点是：图片作为工具调用的返回结果时，Agent 无法直接理解。举个例子，Agent 用浏览器自动化工具截了一张页面图，然后需要判断页面上是否有弹窗——纯文本方案根本没有办法可靠地做到这件事。视觉 API 上线后，这个场景终于可以变成：截图 → 图像识别 → 返回文本描述 → 主 Agent 直接决策。

1.2 视觉能力解锁的典型 Agent 场景

有了视觉 API，Agent 能处理的场景一下拉开了深度。我按使用频次和成熟度梳理了一下，最值得关注的集中在表格里这几类：

这五类场景有一个共同点：都不是新需求，早就存在，只是因为过去接入成本高、识别结果不够稳定，才一直停留在"人工处理"阶段。视觉 API 把每张图的花费压到不足一分钱之后，成本门槛没了，Agent 把这些能力接到自动化流程里就顺理成章了。

2. 视觉 API 的定价逻辑与成本拆解

单张图 0.001 元这个数字，很多人的第一反应是"这也太便宜了"。但用的时候要注意，不是所有图片都按这个价。理解背后的计费逻辑，才能在设计 Agent 流程时把成本控制住。

2.1 "0.001 元/张"是怎么算出来的

视觉 API 的计费方式通常不是按"张"计价，而是按图片消耗的视觉 token 数计价。单张图 0.001 元，对应的是"一张经过适当压缩的普通图片"所消耗的 token 数，而不是"不管什么图都是 0.001 元"。

一张图片进入视觉模型之前，会被切分成若干个视觉切片（有些模型叫 tile 或 patch），每个切片对应一定数量的 token。图片分辨率越高、长宽比越特殊，切片数量越多，token 消耗就越大。我做了个简单的对照估算表，可以直观感受一下（以下数字基于常见的视觉模型计费规则）：

所以"0.001 元/张"更适合理解成一种营销化的表述，本质是"常规图片的典型成本落在很低区间"。真正合理的做法是设计流程时先对图片做统一压缩和尺寸规范化，把成本控制在那张"0.001 元"的参考线附近。

2.2 和自建视觉模型、云厂商方案的对比

为什么这个价格能在 Agent 场景里成为基础设施？需要放在对比里看。

自建视觉模型的成本大头在显存。以常见开源 VLM 为例，光模型权重就要占 10GB 以上显存，推理时 KV Cache 再叠加上去，一张主流显卡可能只够跑一个低并发实例。团队还要承担训练数据收集、微调、版本迭代这些隐性成本。除非有数据合规强需求或者调用量大到上千万次级别，否则自建方案的综合成本很难低于按量付费的 API。

通用云厂商的多模态 API 也成熟，但价格通常在每千张几十到上百元的区间。如果你的 Agent 每天处理几千张图，这个成本不是不能接受，但离"高频调用"还有距离。

DeepSeek 视觉 API 的意义在于把单次调用的边际成本打到了接近零的水平。Agent 在高频工作流里可以放心地对每张截图、每个界面状态都做一次视觉理解，不用再纠结"这次的图片值不值得调一次模型"。

2.3 成本失控的防护办法

便宜归便宜，量一旦上去，积少成多依然能产生让人肉疼的账单。我见过好几个团队把 Agent 接上视觉 API 跑了一周之后发现费用不对，排查下来都是同一个原因：循环里反复对同一张图做了识别。

控制成本的几个实用做法：

• 对图片统一做预处理，缩放到合理尺寸后再上传，避免超大图造成 token 翻倍；
• 在 Agent 上下文或外部缓存里记录已识别图片的摘要，同一张图重复出现时直接复用结果；
• 为视觉工具设置单日调用上限，超出后自动降级为人工处理或跳过；
• 对图片做缓存 key 设计时，优先用内容哈希而不是 URL，避免同一张图在不同地址下被重复识别。

这套逻辑和调用 LLM 文本接口省钱的手法一样：能缓存就缓存，能压缩就压缩，别让不必要的重复请求吃掉预算。

3. 实操：把视觉 API 接进 Agent 的标准动作

铺垫了这么多，直接进入代码环节。下面这套接入方案是我在实际项目里用过的流程，从环境准备到工具注册完整走一遍。假设你的 Agent 主模型还是 DeepSeek 的文本模型，视觉 API 作为独立工具模块被调度——这也是目前最灵活、对 Agent 框架侵入最小的接法。

3.1 环境准备与密钥安全

视觉 API 兼容 OpenAI 的调用格式，所以不需要额外引入特殊依赖，直接用 OpenAI SDK 就可以。Python 环境下的安装：

pip install openai

然后配置鉴权信息。我这里强烈建议用环境变量而不是直接在代码里写死密钥，否则一旦代码推到 Git 仓库，密钥泄露就是安全事故：

export DEEPSEEK_API_KEY="sk-xxxxxxxx"

也可以写到 .env 文件里，加载方式随你使用的框架而定。初始化客户端的标准写法如下：

import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com" )

注意一点：如果你的 Agent 框架内部已经有一个"大模型客户端"实例，视觉调用尽量复用同一个 client 配置，不要额外创建新实例，否则在并发场景下容易撞上连接数上限。

3.2 图像输入格式：URL 与 Base64 的选择

视觉 API 接收图片的常见格式有两种：图片 URL 和 Base64 编码数据。

URL 方式最简单，前提是图片可以被外部访问。如果 Agent 从浏览器工具拿到的是临时文件地址，或者从对象存储里拿到了 CDN 链接，直接拼进消息即可。

response = client.chat.completions.create( model="deepseek-vision", # 以实际模型名为准 messages=[ { "role": "user", "content": [ {"type": "text", "text": "这张图里有什么？用结构化方式描述。"}, {"type": "image_url", "image_url": {"url": "https://example.com/screenshot.png"}} ] } ] )

Base64 方式适用于图片在本地、或者来自工具返回的字节流数据。这种方式绕开了外网可达性问题，在 Agent 内部工具链里更常见。

import base64 with open("screenshot.png", "rb") as f: img_base64 = base64.b64encode(f.read()).decode("utf-8") response = client.chat.completions.create( model="deepseek-vision", messages=[ { "role": "user", "content": [ {"type": "text", "text": "提取这张图片里的关键信息。"}, {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_base64}"}} ] } ] )

需要提醒的是，Base64 编码会比原始文件增加约 33% 的传输体积。如果图片本身已经有 5MB，编码后接近 7MB，网络传输延迟和失败概率都会上升。我的实践是：进入 API 前先压缩图片，既能降低传输开销，也能压低视觉 token 消耗，一举两得。

3.3 调通一次"看图"的最小示例

完整的最小示例，加上结果输出：

import os import json from openai import OpenAI client = OpenAI( api_key=os.environ.get("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com" ) def analyze_image(image_path: str, instruction: str = "描述图片内容") -> str: import base64 with open(image_path, "rb") as f: img_b64 = base64.b64encode(f.read()).decode("utf-8") response = client.chat.completions.create( model="deepseek-vision", messages=[ { "role": "user", "content": [ {"type": "text", "text": instruction + " 请用 JSON 格式输出。"}, {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_b64}"}} ] } ], temperature=0.1 ) return response.choices[0].message.content # 实际调用 result = analyze_image("./screenshot.png", "识别这个页面里是否有弹窗，如果有，描述弹窗内容和关闭按钮位置。") print(result)

这里把 temperature 调低是有意的。视觉识别任务在大多数场景里属于"信息抽取"，不是"创意生成"，温度调低能减少模型输出多余描述和幻觉内容的概率。如果你需要模型对图表做解读并生成结论，可以适当调高到 0.5 左右，但依然建议先低温跑一版再决定。

3.4 把视觉能力注册成 Agent 工具

光能调用还不够，要在 Agent 工作流里真正发挥作用，得把它包装成一个工具函数。以常见的 Function Calling 模式为例：

def visual_understanding(image_path: str, task: str) -> str: """ 视觉理解工具： - image_path: 图片路径或 URL - task: 需要模型完成的任务描述，比如"提取表格数据""识别按钮状态" """ result = analyze_image(image_path, task) return result

然后在 Agent 的 tools 定义里注册这个函数，并加上清晰的描述。工具描述一定要写好，这直接影响主模型在什么场景下决定调用它——描述越具体，模型调用越准确。

tools = [ { "type": "function", "function": { "name": "visual_understanding", "description": "当 Agent 需要理解截图、图表、扫描件、照片中的内容时调用，返回结构化文本描述", "parameters": { "type": "object", "properties": { "image_path": {"type": "string", "description": "图片路径或 URL"}, "task": {"type": "string", "description": "需要执行的分析任务"} }, "required": ["image_path", "task"] } } } ]

注册完成后，Agent 在收到图片或者从浏览器工具拿到截图时，就会自动决定调用 visual_understanding，而不是瞎编一个回应。

4. Agent 多模态化的架构设计与上下文管理

接上 API 只是第一步，要让视觉能力长期稳定地跑在 Agent 流程里，有几个架构层面的问题必须想清楚。我按照实际项目里踩过的坑来展开。

4.1 视觉结果如何进入 Agent 记忆与上下文

视觉 API 返回的是纯文本，所以进入 Agent 上下文的天然是文本。这个设计其实挺省心的，不需要为"图像记忆"额外设计向量存储。

但有个细节容易忽略：如果 Agent 在后续步骤里需要再次查看同一张图片，你不能只保留之前的文本描述，得保留图片的引用标识或者临时缓存路径。原因很简单——文本描述是经过一次模型压缩的信息，永远可能存在遗漏。比如第一步模型说"页面顶部有一个红色按钮"，第二步你想知道按钮上的具体文字，前一回的文本描述里可能就没有记录。

我采用的模式是：视觉工具返回结果时，除了返回文本描述，还会把"图像引用"一并存入 Agent 的上下文，让后续决策可以拿到原图引用。伪代码大概是：

result = { "summary": "图片显示一个登录表单，包括用户名和密码输入框", "image_ref": "local://screenshots/20250112_1024.png", "cached_result_id": "vis_abc123" }

之后如果 Agent 需要深入分析某个局部区域，可以带着 image_ref 再次调用视觉 API，指定"只看图片左上角区域"，这样不会丢失原始图像信息。

4.2 控制视觉 token 在上下文中的占用

Agent 的上下文窗口是有限的。一张图片算下来虽然只要几百上千 token，但如果每次工具调用都把整张图的编码塞进消息历史，连续跑几个来回，上下文很快就满了。

解决办法是"用完即走"的通信模式设计：图片内容只在视觉工具调用时传给视觉模型，视觉模型返回的文本摘要才进入主 Agent 的上下文。原始图片不常驻主上下文，只在需要深入分析时通过 image_ref 按需重新加载。

这样做的效果很直观：上下文里是干净的文本流，Agent 可以保持长对话而不被图片 token 塞爆，视觉模型又能在需要时获得完整图像信息，两头都不耽误。

4.3 多模态工具链串联的实战案例

拿浏览器自动化场景举例，一个典型的视觉 Agent 工作流：

1. Agent 驱动浏览器工具打开目标页面并截图；
2. 截图传给视觉 API，识别页面状态："存在登录弹窗，弹窗标题为'安全验证'"；
3. Agent 根据识别结果决策：需要输入验证码，或调用其他工具处理；
4. 浏览器工具执行下一步操作，再次截图确认；
5. 循环直到页面状态符合预期。

整个链路里，Agent 的主模型一直是文本模型，但通过视觉工具的加持，它获得了"看屏幕"的能力。这种 design pattern 在行业里也叫"Agent harness"——主模型做推理，工具负责感知和行动。视觉 API 上线后，感知层的最后一块短板也被补齐了。

5. 常见报错与排查技巧实录

最后这部分列一下我实际接入过程中遇到的坑和排查思路。有些错误信息看起来和视觉 API 无关，但恰恰是多模态 Agent 集成中最容易触发的问题。

5.1 工具调用结果没有立即返回

常见报错信息类似于 "messages tool calls need immediate results"。这类报错经常出现在 Agent 框架里：模型发出 tool_calls 指令后，系统在规定轮次内没有把工具执行结果追加回消息列表。

原因往往是 Agent 框架里的视觉工具实现为了"异步处理"而把结果延迟到了下一轮，或者工具内部出现了超时错误，但没有把错误信息返回给模型。解决办法：

• 确保工具函数同步返回结果，即使调用失败也要把错误字符串返回给模型，让模型决定重试还是走降级路线；
• 检查 Agent 框架中对 tool_calls 的响应处理是否在同一循环内完成，不要引入额外的用户交互。

这类报错不是视觉 API 独有的，但既然 Agent 加了视觉工具，排查时优先检查工具注册和执行链路是否完整。

5.2 图片文件格式与大小问题

视觉 API 支持的格式一般包括 JPEG、PNG 等常见格式。实际测试中我遇到两个高频问题：

第一个是 PNG 太大。截图工具保存的高清 PNG 动辄 5MB、10MB，直接 Base64 编码简直是在惩罚自己。解决思路是先压缩，用 Pillow 转成 JPEG 并缩放：

from PIL import Image img = Image.open("screenshot.png") img = img.convert("RGB") img.thumbnail((1280, 1280)) img.save("screenshot_compressed.jpg", "JPEG", quality=85)

第二个是透明背景的问题。PNG 带透明通道直接转 JPEG 会变成黑底，影响识别效果。转 JPEG 前先铺一层白色背景。

from PIL import Image img = Image.open("screenshot.png").convert("RGBA") background = Image.new("RGB", img.size, (255, 255, 255)) background.paste(img, mask=img.split()[3]) background.save("screenshot_white.jpg", "JPEG", quality=85)

这类细节看着小，在批量识别场景里直接影响识别准确率和成本。

5.3 并发调用的限流与重试

视觉 API 作为 Agent 的高频工具，在并发场景下很容易触及限流。我在测试时遇到过请求排队变长的现象。建议在客户端加渐进式重试逻辑：

import time def call_with_retry(func, max_retries=3): for attempt in range(max_retries): try: return func() except Exception as e: if attempt == max_retries - 1: raise e time.sleep(2 ** attempt) # 指数的形式退避

同时为调用侧设置合理的并发上限。Team 里多个 Agent 实例共享同一个 API Key 时，最好估算一下并发总量，避免单个流程的循环触发雪崩。

5.4 识别结果不可靠时的降级方案

视觉 API 再强，也有翻车的时候。表格结构太复杂、图片分辨率太低、手写文字潦草，都会导致识别结果质量下降。生产环境里一定要设计降级链路，不能把视觉 API 当作唯一的信息来源。

我的建议是：关键决策场景用"双通道验证"。比如视觉 API 识别出表格数据后，再用规则引擎对输出做格式校验，数值类字段做范围判断，异常结果触发人工复核队列。这样 Agent 自动化流程既享受了视觉能力带来的效率提升，又不至于因为一次识别错误在网上跑出离谱的业务结果。

写在最后

实际测试一圈下来，我最大的体会是：视觉 API 的接入难度真的被压得很低，难的部分全在接入之后——上下文怎么管理、成本怎么控制、识别结果怎么和业务逻辑校验。把视觉能力放在 Agent 的工具层而不是模型层，是我目前认为最灵活的做法。最后分享一个小技巧：开启本地缓存，同一张图片的视觉描述结果缓存起来，二次出现直接命中缓存，能省下不少调用费。如果你的 Agent 和截图、图表打交道比较频繁，建议现在就给它装上眼睛。