Grok 4.7 API 教程：构建一个 AI 电路设计审阅器

电路原理图是一种展示电子元件如何连接的图示。审阅原理图意味着检查元件及其参数是否满足设计需求。电源是否能提供足够电流？处理器能否读满传感器的输出范围？答案来自原理图、器件数据手册，以及少量计算。

我想看看 Grok 4.7 能否完成整套审阅工作。根据Grok 4.7 指南，该模型针对更长任务进行了训练，并会更仔细地自检。电路还能提供普通 Python 代码可验证的数值，因此我们无需另一个 AI 模型来评判结果。

为做实验，我制作了 EnviroNode Rev A，一个 USB 供电的小型传感器板，并在其设计中植入了三个故障。未告知 Grok 故障数量。它必须自行找出问题，用元件文档支持每一条结论，提出修正，并将修正后的数值提交给 Python 检查。

您无需电气工程背景即可跟进。每当出现一条电路规则时，我都会先行解释。您将学到如何：

• 通过 Responses API 向 Grok 4.7 发送原理图图像

• 使用 Files API 附加数据手册，并让 Grok 在其中搜索

• 使用 代码执行 校核计算，并用 网页搜索 查找限制

• 为 Grok 提供本地 verify_design() 函数来判定通过或失败

• 在模型上下文限制内维持一段冗长、文档密集的对话

• 返回一致的审阅格式，并比较不同推理等级

同一块电路板从首张图像审阅一直贯穿到最终的 Python 校验。

要点速览

在获得数据手册后，Grok 4.7 识别出每个植入故障，且修正后的设计通过了 Python 校验。这反映的是这三个故障的情况，并非普遍电路审阅能力。

• 没有文档时，Grok 拒绝猜测：仅凭图像确认了一个缺陷，而稳压器和模数转换器（ADC）限制被归入“需要证据”。
• 数据手册将怀疑转化为证据：每条发现均引用了文档数值，且未误报正确元件。
• 文件密集型回合可能耗尽长上下文：在多次 PDF 搜索后，一次续传超过 500K 窗口；修正后的循环会在下一回合前进行压缩。
• 低推理通过了验证器但暴露盲点：其滤波参数满足书面检查，但未测试容性负载与建立时间行为。

这只是一块小板子，不是基准测试。若一块板需十几本数据手册，所需上下文更大，结果也可能不同。

什么是 Grok 4.7 API？

Grok 4.7 API 通过模型 ID grok-4.7 为 Python 应用提供文本与图像输入、文本输出，以及 500,000 令牌的上下文窗口。官方指南列出了 low、medium、high（默认）和 xhigh 推理等级；推理不可关闭。API 亦支持函数调用、结构化输出、网页搜索、X 搜索，以及代码执行。

我们的Grok 4.7 概览涵盖了发布与基准。SpaceXAI 将 Chat Completions 标记为旧版，因此此处所有示例均使用Responses API。

Grok 4.7 多少钱？

当提示（prompt）少于 200,000 个令牌时，Grok 4.7 的价格为每百万输入令牌 $2、每百万缓存输入令牌 $0.50、每百万输出令牌 $6。一旦提示达到 200,000 个令牌，该请求内的每个令牌计费将变为 $4、$1 和 $12。

服务端工具单独计费：定价页面对每 1,000 次网页搜索或代码执行调用收取 $5。对附加文档的搜索每次 1 美分，且存储的文档还按 GiB/天计费。对于相关请求请使用稳定的 prompt_cache_key，但也要为未缓存输入做预算。

从 usage.cost_in_usd_ticks 读取计费成本。成本跟踪文档称其包含缓存与工具费用。将该值除以 10^10 即为美元。

为何用电路设计来测试 Grok 4.7？

电路设计在一项任务里同时考察文档阅读、计算、工具使用和验证。SpaceXAI 报告 Grok 4.7 在 EEBench 上为 64.0%。EEBench 方法采用仿真与 BOM 检查，而非由大语言模型（LLM）评判，EnviroNode 也遵循同样原则。

我们要构建什么：EnviroNode Rev A 电路审阅

EnviroNode Rev A 是一个 USB 供电的传感器节点。您可从GitHub 下载完整项目。

原理图包含 Grok 审阅所需的全部元件参数。每条要求都有一个 ID，如 PWR-002 或 BW-001，因此每条发现都能回溯到相应规则。

带取值的 EnviroNode Rev A 原理图。作者供图。

在 Grok 审阅该板之前，公开验证器将使用的每条规则。该函数基于以下八项要求返回五项通过/失败检查：

• PWR-001： USB 输入保持在 4.75 V 至 5.25 V 之间
• PWR-002： 稳压器覆盖峰值负载
• PWR-003： 非 MCU 负载使用 10 mA 预算
• SIG-001： 传感器满量程为 1.0 V
• ADC-001： ADC 输入不高于 2,250 mV
• ADC-002： ADC 输入至少达到 1,500 mV
• BW-001： 通过 100 Hz 的信号衰减小于 1 dB
• BW-002： 滤波器截止频率不高于 500 Hz

模型接收相同的要求集合。没有哪条验证器限制会仅在 Grok 提出修复后才出现。

三个植入缺陷是什么？

这三个故障都可用数值检验。其数量不包含在提示中。

• 稳压器过小（PWR-002）：TI TLV700 额定 200 mA，而 ESP32-C3 数据手册列出 Wi‑Fi 发射峰值 335 mA，且乐鑫的原理图检查清单建议至少 500 mA。

• ADC 超量程（ADC-001）：增益为 3 会使 ADC 端达到 3.0 V，但数据手册的有效范围上限为 2,500 mV，而要求允许其 90%。

• 滤波过慢（BW-001）：10 kΩ 与 1 µF 给出 15.9 Hz 截止，而至多 100 Hz 的信号衰减不得超过 1 dB。

ADC 缺陷涉及测量范围，而非引脚损坏。正确的选择（如 LED 电阻与 CHIP_EN 延时）使误报可量化。

审阅循环如何运作？

审阅需要明确边界：Grok 提出改动，而 Python 负责判定通过或失败。下图展示文档与工具在循环中的位置。

审阅循环将方案与验证分离。作者供图。

在第一次 API 调用前定义成功标准。仅当 Grok 将缺陷与某条要求及支持证据关联起来时，才计为一条缺陷；仅当 verify_design() 返回 all_pass = true 时，才计为修复完成。

如何在 Python 中设置 Grok 4.7 API

您需要一个已预存额度的 xAI API 密钥、Python 3.10 或更新版本，以及将 OpenAI Python SDK 指向 xAI 基础 URL。请在 xAI 控制台创建密钥，然后安装下方所用软件包。

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install openai python-dotenv pydantic httpx streamlit
pip install matplotlib schemdraw pytest  # 可选的图表与验证器测试

API 示例使用第一组软件包；第二组用于仓库图示与测试。我使用 Python 3.11.9、openai 3.19.2、pydantic 2.13.5、streamlit 1.64.0 和 httpx 0.28.1 进行了测试。将密钥保存为环境变量 XAI_API_KEY，并用 python-dotenv 加载，而不是写入源码；如果您对此不熟悉，可参见我们的虚拟环境指南。

发起您的首个 Grok 4.7 API 调用

如果您的密钥已能与 Responses API 正常工作，请跳到步骤 1。否则，此请求可一次性检查密钥、基础 URL 和模型 ID。

import os
import httpx
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(api_key=os.environ["XAI_API_KEY"], base_url="https://api.x.ai/v1",
                timeout=httpx.Timeout(3600.0))

response = client.responses.create(
    model="grok-4.7",
    reasoning={"effort": "low"},
    input="In one sentence, what does a low-dropout regulator do?",
)
print(response.output_text)

若返回一句话答案，说明设置成功。更长的超时稍后很重要，因为使用推理与工具的请求可能耗时数分钟。

步骤 1：Grok 4.7 能仅凭图像审阅电路吗？

可以。只要提示清楚说明不会再调用工具，Grok 4.7 就能仅凭图像审阅原理图。基线做法是将 PNG 作为 base64 data URL 连同要求文本一起发送。

image = {
    "type": "input_image",
    "image_url": f"data:image/png;base64,{SCHEMATIC_B64}",
    "detail": "high",
}
response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": [
        image,
        {"type": "input_text", "text": REVIEW_PROMPT},
    ]}],
)

提示要求输出三部分：已确认、需要更多证据、已检查且可接受。未提及缺陷数量或可疑元件。

仅图像审阅发现了什么？

当没有工具或数据手册可用时，请明确告知模型。否则，它可能在表示要查规范后，由于无法访问而提前结束响应。

正如要点速览所述，Grok 确认了滤波缺陷：截止 15.9 Hz，100 Hz 处衰减 16.1 dB。它将稳压器与 ADC 置于“需要更多证据”，而非猜测其限制。

步骤 2：如何使用 Files API 添加数据手册

附加文档能将模糊担忧变成有据可依的结论。每份文档只需上传一次，并通过 file_id 引用。

with open(DATASHEET_PATH, "rb") as datasheet:
    uploaded = client.files.create(
        file=datasheet,
        purpose="assistants",
        expires_after={"anchor": "created_at", "seconds": 7 * 24 * 3600},
    )
content = [image, *[{"type": "input_file", "file_id": fid} for fid in file_ids],
           {"type": "input_text", "text": EVIDENCE_PROMPT}]

由于本教程将 expires_after 设为 7 天，缓存的 ID 仅在该窗口内有效。若不设置 expires_after，xAI 会保留已上传文件，直至您删除。

在此处捕获的 OpenAI SDK 响应中，附件搜索表现为名为 pdf_search 与 pdf_browse 的 custom_tool_call 项，而用量统计则计入 document_search_calls。这只是观察到的行为，不是通用工具类型契约，因此循环还会检查文档化的用量计数器。

数据手册如何改变审阅？

这些文档解决了步骤 1 中的两个开放问题，并为电源、ADC 与滤波结论提供了支持。关于稳压器，结论引用了 TLV700 的 200 mA 额定值、ESP32-C3 的 335 mA 发射峰值，以及 500 mA 的供电建议。

针对滤波，Grok 推导出在 R5 不变时同时满足两条带宽规则的电容取值：大致 32 至 81 nF。所有“障眼法”元件均被归入“已检查且可接受”，并说明原因。

步骤 3：如何用 Grok 4.7 代码执行验证计算

代码执行是 xAI 的服务端 Python 沙箱，在使用 OpenAI 客户端时作为 tools 中的 {"type": "code_interpreter"} 添加。提示新增一条规则：凡含数值的结论，必须先算出来才算确认。

先前链接的代码执行指南称沙箱无网络访问，且请求间不保留状态。对于少量数据手册数值，这没有问题。

Grok 应该校核哪些计算？

让 Grok 在一个脚本中检查功耗预算、ADC 范围与滤波带宽。如果电路不是您的强项，可以跳过下方输出；关键信息在其后。

f=  100.0 Hz  |H|=0.157177  attenuation=16.0722 dB
fc required for <= 1 dB at 100 Hz: fc >= 196.5227 Hz
V_adc_fs = 3.0000 V
90% limit = 2.2500 V
required rating = max(headroom, mcu min) = 500.00 mA

196.5 Hz 的最低截止频率是滤波修复所依赖的数值，并且由代码计算得出，而不是留给模型心算。即便在衰减最小的容差角落，100 Hz 处也损失超过 15 dB，因此结论成立。

步骤 4：Grok 4.7 能通过 API 搜索网页吗？

可以。网页搜索用于检查附加文档是否仍然最新，因为厂商可能在模型训练截断后修订数据手册。将搜索限制在官方域名，确保证据来自一方权威。

tools = [
    {"type": "code_interpreter"},
    {"type": "web_search", "filters": {"allowed_domains": ["ti.com", "espressif.com"]}},
]

前述网页搜索指南允许最多五个 allowed_domains，包含子域，如 docs.espressif.com。即使附加的数据手册是最新版本，我仍会保留此步骤，因为它能捕捉到您上传后发布的修订。

引用能证明什么？

Grok 应引用当前 TI 产品页、ESP32-C3 文档、硬件清单及相关勘误。将这些引用视为来源证据，而非工程结论正确性的证明。

域名过滤仍可能返回不相关页面。请核查每条引用是否支持用于计算的确切元件与限制。

Grok 搜索文件、计算、核对来源。作者供图。

步骤 5：如何用 Grok 4.7 函数调用添加验证器

verify_design() 是在您机器上运行的纯 Python 函数，也是唯一的通过与否裁决者。Grok 通过 函数调用 提交设计取值，而该函数按固定限制检查。

VERIFY_DESIGN_TOOL = {
    "type": "function",
    "name": "verify_design",
    "description": "Deterministically check an EnviroNode revision against EN-REQ-001...",
    "parameters": {
        "type": "object",
        "properties": {
            "revision": {"type": "string"},
            "regulator_part": {"type": "string"},
            "gain_rf_ohm": {"type": "number"},
            "gain_rg_ohm": {"type": "number"},
            "filter_r_ohm": {"type": "number"},
            "filter_c_nf": {"type": "number"},
        },
        "required": ["revision", "regulator_part", "gain_rf_ohm",
                     "gain_rg_ohm", "filter_r_ohm", "filter_c_nf"],
    },
}

电源能力需满足 max((335 + 10) mA × 1.25, 500 mA)。对于 ADC，1.0 V × (1 + Rf/Rg) 必须保持在 1,500 到 2,250 mV 之间。滤波检查测量 100 Hz 处的衰减，并将截止频率限定在 500 Hz；每项检查返回测量值、限制与通过/失败。

工具模式仅告诉 Grok 需要发送哪些值。核心的通过/失败逻辑就是普通 Python：

import math

part = PARTS.get(regulator_part.strip().upper())
required_ma = max((335 + 10) * 1.25, 500)
power_ok = (
    part is not None
    and float(part["rated_iout_ma"]) >= required_ma
    and float(part["vin_max_v"]) >= 5.25
    and float(part["vout_v"]) == 3.3
)

gain = 1 + gain_rf_ohm / gain_rg_ohm
adc_mv = gain * 1000

fc = 1 / (2 * math.pi * filter_r_ohm * filter_c_nf * 1e-9)
loss_db = 10 * math.log10(1 + (100 / fc) ** 2)

checks = {
    "PWR-002": power_ok,
    "ADC-001": adc_mv <= 2250,
    "ADC-002": adc_mv >= 1500,
    "BW-001": loss_db <= 1.0,
    "BW-002": fc <= 500,
}
return {"all_pass": all(checks.values()), "checks": checks}

完整函数还会拒绝无效取值，并随结果返回测量。请用已知良好、已知不良、未知元件以及临界未通过的设计进行测试。

为何应由代码而非模型来打分？

将元件额定值排除在模型控制之外。我不会让模型自己提供电流额定值。Grok 仅发送料号，函数在应用目录中查找额定值。

在可以用代码检验答案时，不应让代理同时提出方案并裁定正确与否。任务变化时，将 verify_design() 替换为测试套件或模式检查。编写验证器需要额外工作，但其通过与否不取决于模型意见。

步骤 6：如何重设并验证电路

给 Grok 一个目标：用尽可能少且合理的改动修复每一条已确认的违规，并且在先前定义的检查通过之前，不要宣布设计完成。提供步骤 3 至 5 的证据与工具，然后设置请求上限。

这就是“要点速览”中上下文警告的重要所在。请在增加更多回合前解决它。

为何文件密集的循环需要上下文压缩？

一次续传会包含较早的工具结果，而文档搜索可能返回大量文本。在失败的原型中，下一次续传达到 1,116,321 个令牌，超出 Grok 4.7 的 500,000 令牌窗口。

上下文压缩无法拯救已超限的请求。修正后的循环会在每一次成功的文档搜索回合后再发下一个请求之前进行压缩。

details = (response.usage.model_extra or {}).get(
    "server_side_tool_usage_details", {}
)
observed_attachment_call = any(
    item.type == "custom_tool_call"
    and item.name in {"pdf_search", "pdf_browse"}
    for item in response.output
)
used_documents = (
    details.get("document_search_calls", 0) > 0
    or observed_attachment_call
)

if used_documents:
    compacted = client.responses.compact(
        model="grok-4.7", input=history + list(response.output) + follow_up)
    history = list(compacted.output)  # 原样传回压缩项
    # 压缩会丢弃工具输出，因此我们需自行重述验证器裁决。
    history.append({"role": "user", "content":
                    "verify_design results, exactly as returned: " + json.dumps(results)})
else:
    history = history + list(response.output) + follow_up
response = client.responses.create(model="grok-4.7", input=history, tools=TOOLS,
                                   store=False, prompt_cache_key=cache_key)

保留最后那个 append。压缩会丢弃冗长的工具输出，因此重述验证器结果有助于下一个响应避免臆造或混淆的检查。对每个文档密集回合后进行压缩是保守做法；更大的系统可依据输入令牌阈值触发。

Rev B 通过验证了吗？

通过。Grok 在每个失败子系统（电源、ADC 增益、滤波带宽）各更换了一个元件。图示展示了 Rev A 与 Rev B 的具体取值。

三个元件改动修正了 Rev A。作者供图。

修订后的取值随后提交给 verify_design()。它会针对每条要求返回一项结果。

修订设计通过所有验证检查。作者供图。

若结果为失败，将作为 function_call_output 返回，因此 Grok 可继续修订设计，直到检查通过或达到请求上限。

步骤 7：如何返回结构化电路审阅

结构化输出 返回符合模式的对象，而非需您解析的散文。请在同一会话中调用 client.responses.parse() 并传入 Pydantic 模型，同时关闭工具调用。

class Finding(BaseModel):
    violated_requirement: str
    severity: Literal["blocker", "major", "minor"]
    evidence: list[str]
    recommended_change: str
    verifier_result: Literal["pass", "fail", "not_verified"]

parsed = client.responses.parse(
    model="grok-4.7", input=history + [REPORT_REQUEST],
    text_format=DesignReview, tools=TOOLS, tool_choice="none", store=False,
)

有效的模式并不能证明内容正确，因此请包含验证器结果，并让 Grok 基于该结果设置 verifier_result。随后即可将 JSON 投入问题跟踪器或人工审批队列。

结构化审阅报告了什么？

结构化报告应将每条原始缺陷标为已解决，引用验证器返回的测量值，并将未测试的担忧保留在 open_risks 中。对于该设计，这些担忧包括稳压器恰好位于 500 mA 下限，以及与乐鑫建议不同的 ADC 电容。

更高的 Grok 4.7 推理力度能提升电路审阅吗？

更高力度并未提升验证器得分，但改变了滤波修复的质量。每个级别接收相同的原理图、提示、工具与请求上限。

low 降低了电阻并保留 1 µF 电容，使容性负载与建立时间行为落在验证器之外。Microchip 的容性负载指南称串联电阻可改善稳定性，因此此结果并不能证明修复不稳定；它提示需进行频响、阶跃响应或台架测试。high 则改了电容，而 xhigh 在多一次验证器调用后与 high 选定相同最终取值。

何时值得使用 xhigh 推理？

仅就这一次对比，high 的平衡更好。它避免了未建模负载的担忧，也没有像 xhigh 那样多一次验证器调用。每级只执行一次无法建立普适排名。

Grok 4.7 修好电路了吗？

对开篇问题的答案是肯定的，在验证器的五项检查范围内。下表将前述发现浓缩于一处。

• 图像与要求
  • 增益：目视检查
  • 结论：确认仅凭原理图可证明的内容
• 数据手册
  • 增益：厂商限制
  • 结论：将两项开放问题转化为明确发现
• 代码执行
  • 增益：核对过的计算
  • 结论：量化电源与滤波问题
• 网页搜索
  • 增益：最新官方来源
  • 结论：检查附加证据是否仍为最新
• 本地验证器
  • 增益：来自 Python 的通过或失败
  • 结论：仅接受通过每条规则的修订

Grok 修复了编码的要求。它并未证明修订后的电路板在电气上是完整的或可量产。

文档决定某项担忧是否有证据；Python 决定某个修订是否通过。流畅的文字不能替代任何一方。

在 Streamlit 中观看审阅过程

我们的Streamlit 指南介绍了此处使用的界面。它通过流式传输展示实时到达的工具调用，然后显示验证器检查与最终报告。