如何使用GPT-6.1 Terra：API设置、推理努力与工具调用

通往GPT-6.1 Terra的最短路径是Responses API。然而，一个有用的实现需要的不仅仅是模型ID。它应该定义任务、选择推理级别、以适当的细节设置提供图像、验证输出，并限制任何可能改变外部状态的工具。

本教程使用当前OpenAI API约定和模型ID gpt-6.1-terra。它侧重于视觉审查工作流程，因为这符合Terra的官方定位。

开始之前

您需要一个能够访问GPT-6.1 Terra的OpenAI API项目、一个存储在源代码之外的API密钥，以及最新的OpenAI SDK。目前模型页面显示免费套餐不支持API，因此请直接在您的项目中验证访问权限，不要假设ChatGPT套餐的访问权限与API访问权限相同。

安装 Python SDK：

pip install --upgrade openai

通过您的 shell 或密钥管理器设置 OPENAI_API_KEY。请勿将生产密钥粘贴到脚本、截图、存储库或客户端应用程序中。

发起一个基本文本请求

from openai import OpenAI

client = OpenAI()

= client.responses.create(
    model="gpt-6.1-terra",
    reasoning={"effort": "中等"},
    instructions=(
        "撰写简洁的生产说明。区分可见证据"
        "来自推理，并在提供的材料不足时说明情况。"
    ),
    input="将这条评论笔记转化为一份清晰的五项行动清单：..."
)

print(response.output_text)

OpenAI 建议使用 Responses API 进行直接模型请求和推理模型。instructions 值适用于当前请求。将稳定的行为指导放在那里，并让用户输入专注于具体任务。

分析图像

Terra接受图像输入并返回文本。一个Responses请求可以包含文本和图像URL：

# 此脚本用于演示如何从视频中提取音频

from openai import OpenAI

client = OpenAI()

= client.responses.create( model="gpt-6.1-terra", reasoning={"effort": "中等"}, input=[{ "role": "user", "content": [ { "type": "input_text", "text": ( "审查此广告活动图片。仅报告可见的问题" "包含裁剪、文字放置、对比度和标志安全。" "针对每个问题，指出可见区域并提出修复方案。" ), }, { "type": "input_image", "image_url": "https://example.com/asset.jpg", "detail": "高", }, ], }], )

print(response.output_text)

支持的图片格式包括PNG、JPEG、WEBP以及非动画GIF。OpenAI的视觉指南也支持Base64数据URL。图片会消耗令牌，因此请使用与任务相匹配的分辨率和细节级别。对于密集或坐标敏感的屏幕，在支持的情况下，`original`可能合适；对于初步粗略审查，`low`可能就足够了。在标准化设置之前，请核实当前特定于模型的尺寸表。

## 有意识地选择推理努力程度

Terra 支持 `none`、`low`、`medium`、`high`、`xhigh` 和 `max`；默认值为 `medium`。增加处理力度可提升困难任务的质量，但也会增加延迟和令牌使用量。

一个合理的评估阶梯是：

- `none`：简单的提取或分类，多步推理带来的价值不大。
- `low`：常规审查、起草或受限工具使用。
- `medium`：混合证据、判断或多步骤工作；此为默认值。
- `high`: 困难的视觉差异、规划或复杂的异常处理。
- `xhigh` 和 `max`：仅在评估显示高价值任务有实质性收益时使用。

当答案失败时，不要自动提高努力程度。首先检查提示词、证据、图像质量、输出契约和验证逻辑。

## 请求结构化输出

生产系统不应在已知模式可用时解析任意文本。Terra支持结构化输出。一个视觉质量检查模式可能需要包含类别、证据、严重程度和建议的问题数组。

确切的SDK辅助语法可能会变化，因此请遵循当前针对您所用语言的“结构化输出”指南。无论语法如何，都要验证返回的对象，并定义当缺少必要证据时应用程序应执行的操作。一个有效的JSON结构仍可能包含不正确的观察结果。

## 通过响应API添加工具

Terra列出的Responses API工具包括网络搜索、文件搜索、图像生成、代码解释器、托管Shell、计算机使用、MCP等。仅暴露任务所需的工具。

对于计算机使用，您的应用程序必须运行或连接一个执行环境，执行允许的操作，返回截图，并根据需要保持会话。OpenAI的安全指南建议：

- 一个隔离的浏览器或虚拟机。
- 网站和操作的允许列表。
- 在页面文本或截图中避免出现凭据信息。
- 在购买、数据传输、删除或其他重大操作前需获得用户批准。
- 步骤、时间和成本限制。
- 验证保存的结果，而不是相信模型的摘要。

页面内容不可信。网页无法授予新权限或覆盖用户的指令。

## 可靠的视觉审查循环

稳健的实现将观察与行动分离：

1. 发送图像和一份狭窄的评审标准。
2. 要求每个发现都有可见的证据。
3. 验证响应模式。
4. 将高严重性或低证据发现转交给相关人员。
5. 如果允许更改，仅暴露必要的编辑或计算机工具。
6. 捕获结果状态并运行验证流程。
7. 保存原始内容、提议的操作、审批、输出以及审核人决定。

对于创意工作，Terra可以将分镜审查转化为结构化的修改简报。创作者随后可以在独立的图像、动画或故事制作工具中应用该已批准的简报。

## 常见实现错误

### 直接发送视频文件

Terra 未列出原生视频输入。提取代表性帧，并在必要时提供转录或镜头元数据。明确说明分析基于这些材料。

### 允许自由形式的工具使用

赋予模型广泛的计算机访问权限会带来不必要的风险。限制工具、域名、操作和数据。在产生后果的节点要求审批。

### 将输出视为事实依据

视觉模型可能会遗漏微小细节或推断出不支持的关系。在错误影响重大的情况下，请使用已知测试用例和人工审核。

### 忽略长上下文定价

Terra 的上下文窗口为 105 万 token，但超过 272,000 输入 token 的提示词将按更高费率计费。请尽可能仅检索相关材料。

## 常见问题解答

### 我可以使用 GPT-6.1 Terra 的聊天补全功能吗？

模型页面将Chat Completions列为一个端点，但指出工具调用需要Responses API。对于新的工具使用实现，Responses是合适的默认选择。

### Terra 支持微调吗？

当前模型页面将微调列为不支持。请使用清晰的指令、检索、示例、模式和评估，而不是围绕微调制定计划。

### 我应该如何测试升级到更高推理能力？

在两个或更多努力级别上运行相同的代表性评估集。比较接受的结果、延迟、令牌使用情况和失败类别。不要仅凭一个令人印象深刻的例子做出判断。

## 实施摘要

通过 Responses API 使用 `gpt-6.1-terra`，从中等努力开始，只给模型提供所需的证据和工具，并验证结构和内容。周围框架的质量——权限、评估、验证和日志记录——与模型选择同样重要。