Fara1.5-27B API完全手册：12种核心工具调用与Python集成示例

任玫椒Fleming

418人浏览 · 2026-08-12 07:02:02

任玫椒Fleming · 2026-08-12 07:02:02 发布

Fara1.5-27B API完全手册：12种核心工具调用与Python集成示例

【免费下载链接】Fara1.5-27B 项目地址: https://ai.gitcode.com/hf_mirrors/microsoft/Fara1.5-27B

Fara1.5-27B是由Microsoft Research AI Frontiers开发的多模态计算机使用代理（CUA），专为Web浏览器设计。它通过截图观察浏览器，并通过发出结构化工具调用（如点击、输入、滚动等）代表用户执行操作，实现端到端任务完成。本手册将详细介绍其12种核心工具调用方法及Python集成示例，帮助开发者快速上手这一强大的AI代理。

核心功能与优势

Fara1.5-27B作为一款先进的Web自动化工具，具备以下显著特点：

端到端Web任务完成：能够填写表单、预订服务、申请工作、规划旅行、管理购物车等，不仅是简单的点击操作，而是朝着目标有序执行一系列动作。
纯视觉感知：仅依靠截图运行，无需访问DOM，与人类用户的输入方式一致。
坐标定位动作：直接预测像素级别的点击和拖动目标，无需单独的定位模型。
安全设计：在输入个人信息、付款、提交、登录、发送消息或其他不可逆操作前，会停止并询问用户，即使技术上可以继续。
超长上下文：262K的上下文长度足以容纳带有完整动作历史的多截图轨迹。

环境准备与安装

系统要求

torch >= 2.11.0
transformers >= 5.2.0
vllm >= 0.19.1
足够内存的GPU集（A6000、A100、H100和B200已测试），建议至少在2个GPU上分片模型。

模型部署

使用vLLM部署Fara1.5-27B的命令如下：

vllm serve microsoft/Fara1.5-27B \
  --dtype bfloat16 \
  --max-model-len 262144 \
  --limit-mm-per-prompt image=10

12种核心工具调用详解

Fara1.5-27B通过<tool_call>...</tool_call>XML块发出动作，其中包含调用computer_use函数的JSON对象。支持的12种核心动作如下：

鼠标操作类

left_click、right_click、double_click、triple_click

用途：在(x, y)坐标处执行鼠标点击操作
参数：x（横坐标）、y（纵坐标）
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "left_click", "x": 500, "y": 300}}</tool_call>

mouse_move、left_click_drag

用途：光标定位和拖动操作
参数：x（目标横坐标）、y（目标纵坐标），拖动操作还需end_x和end_y
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "left_click_drag", "x": 100, "y": 200, "end_x": 300, "end_y": 400}}</tool_call>

键盘操作类

type

用途：键盘输入文本
参数：text（要输入的文本内容）
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "type", "text": "hello world"}}</tool_call>

key

用途：按下特定按键
参数：key（按键名称，如"Enter"、"Tab"、"Backspace"等）
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "key", "key": "Enter"}}</tool_call>

页面导航类

scroll、hscroll

用途：页面滚动操作，scroll为垂直滚动，hscroll为水平滚动
参数：distance（滚动距离，正值向下/向右，负值向上/向左）
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "scroll", "distance": 500}}</tool_call>

visit_url、history_back

用途：浏览器导航，visit_url跳转到指定URL，history_back返回上一页
参数：url（目标URL，仅visit_url需要）
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "visit_url", "url": "https://www.example.com"}}</tool_call>

任务交互类

web_search

用途：执行网络搜索
参数：query（搜索查询词）
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "web_search", "query": "Python tutorial"}}</tool_call>

pause_and_memorize_fact

用途：在轨迹中持久化存储一个事实
参数：fact（要存储的事实内容）
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "pause_and_memorize_fact", "fact": "User's favorite color is blue"}}</tool_call>

ask_user_question

用途：向用户提出澄清问题
参数：question（问题内容）
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "ask_user_question", "question": "What time would you like to book the appointment?"}}</tool_call>

wait

用途：等待指定时间
参数：seconds（等待秒数）
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "wait", "seconds": 5}}</tool_call>

terminate

用途：结束任务并给出最终答案
参数：answer（最终答案内容）
示例：

<tool_call>{"name": "computer_use", "arguments": {"action": "terminate", "answer": "The task has been completed successfully."}}</tool_call>

Python集成示例

以下是使用vLLM的OpenAI兼容端点与Fara1.5-27B进行单步交互的伪代码示例：

# 捕获浏览器截图并转换为base64格式
screenshot_b64 = capture_browser_screenshot()  # base64 PNG

# 构建消息列表，包含系统提示、用户目标和截图
messages = [
    {"role": "system", "content": FARA_SYSTEM_PROMPT},
    {"role": "user", "content": [
        {"type": "text", "text": "Book a table for 2 at a sushi place in Sunnyvale for Friday 7pm."},
        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{screenshot_b64}"}},
    ]},
]

# 调用模型获取响应
response = client.chat.completions.create(
    model="microsoft/Fara1.5-27B",
    messages=messages,
    temperature=0.0,
    max_tokens=2048,
)

# 解析助手的回复，提取工具调用
# 回复将包含思维链文本，后跟<tool_call>{"name": "computer_use", "arguments": {...}}</tool_call>
# 在沙盒浏览器中执行动作，捕获新截图，追加助手回合和工具/观察回合，循环直到模型发出action="terminate"
# 聊天历史中只保留最近的3张截图

完整的代理循环参考实现，包括截图捕获和Docker沙箱，可在MagenticLite中找到。

安全最佳实践

使用Fara1.5-27B时，应遵循以下安全准则：

人工监督：实时监控Fara在网络上的操作，并提供快速停止执行的方法。
沙箱执行：在隔离的容器中运行Fara，不允许访问主机文件、环境变量或敏感凭据。
浏览限制：通过允许列表或阻止列表限制代理可访问的页面范围，以减少接触恶意页面的风险。
信息保护：除非绝对必要且用户已授权，否则不要与代理共享凭据或个人身份信息。
输出验证：Fara可能会产生幻觉、错误归因来源或被欺骗性内容误导，在根据其输出采取行动之前进行验证。

总结

Fara1.5-27B作为一款强大的Web自动化代理，通过12种核心工具调用实现了丰富的浏览器操作能力。本文详细介绍了这些工具的使用方法和Python集成示例，希望能帮助开发者快速掌握Fara1.5-27B的API使用。无论是自动化重复性Web任务，还是构建更复杂的Web代理系统，Fara1.5-27B都能提供强大的支持。

需要注意的是，Fara1.5-27B的训练数据为英文，主要适用于英文环境的Web任务。在高风险领域（法律、健康、财务建议）使用时需格外谨慎，建议配合适当的安全措施和人工监督。

通过合理利用Fara1.5-27B的能力，开发者可以构建出更加智能和高效的Web自动化解决方案，为用户提供更好的服务体验。

【免费下载链接】Fara1.5-27B 项目地址: https://ai.gitcode.com/hf_mirrors/microsoft/Fara1.5-27B