Tutorial da API Grok 4.7: crie um revisor de projetos de circuito com IA

Um diagrama esquemático é um desenho que mostra como os componentes eletrônicos se conectam. Revisá-lo significa checar se os componentes e seus valores atendem aos requisitos do projeto. A fonte consegue fornecer corrente suficiente? O processador consegue ler todo o sinal do sensor? As respostas vêm do esquema, dos datasheets dos componentes e de alguns cálculos.

Eu quis ver se o Grok 4.7 conseguiria fazer essa revisão de ponta a ponta. O guia do Grok 4.7 diz que o modelo foi treinado para tarefas longas e para conferir melhor o próprio trabalho. Um circuito também nos dá números que o Python comum consegue checar, então não precisamos de outro modelo de IA para julgar o resultado.

Para o experimento, construí o EnviroNode Rev A, uma pequena placa de sensores alimentada por USB, e inseri três falhas no projeto. O Grok não sabe quantas falhas existem. Ele precisa encontrá-las, embasar cada achado com documentação dos componentes, propor correções e submeter os valores corrigidos às checagens em Python.

Você não precisa ter formação em engenharia elétrica para acompanhar. Eu explico cada regra de circuito quando ela aparece. Você vai aprender a:

• Enviar uma imagem do esquema para o Grok 4.7 pela Responses API

• Anexar datasheets com a Files API e deixar o Grok pesquisá-los

• Conferir cálculos com execução de código e limites com busca na web

• Dar ao Grok uma função local verify_design() que decide aprovação ou reprovação

• Manter uma conversa longa e carregada de documentos dentro do limite de contexto do modelo

• Retornar um formato de revisão consistente e, depois, comparar níveis de raciocínio

A mesma placa permanece em foco desde a primeira análise por imagem até a checagem final em Python.

Resumo (TL;DR)

O Grok 4.7 identificou todas as falhas inseridas assim que teve acesso aos datasheets, e o projeto corrigido passou nas checagens em Python. Isso diz algo sobre estas três falhas, não sobre revisão de circuitos em geral.

• Sem documentos, o Grok se recusou a chutar: só a imagem rendeu um defeito confirmado; os limites do regulador e do conversor analógico-digital (ADC) ficaram em "precisa de evidências".
• Datasheets transformam suspeita em evidência: cada achado citou um valor de documento, sem marcar nenhum componente correto como defeituoso.
• Turnos pesados em arquivos podem esgotar o contexto: após buscas repetidas em PDFs, uma continuação excedeu a janela de 500K; o loop corrigido compacta antes do próximo turno.
• Low passou no verificador, mas expôs um ponto cego: os valores do filtro atenderam às checagens escritas, mas deixaram comportamento com carga capacitiva e tempo de assentamento sem teste.

Isto é uma placa pequena, não um benchmark. Uma placa com uma dúzia de datasheets cria um contexto maior e pode produzir resultados diferentes.

O que é a API Grok 4.7?

A API Grok 4.7 oferece a apps Python entrada de texto e imagem, saída em texto e uma janela de contexto de 500.000 tokens por meio do ID de modelo grok-4.7. O guia oficial lista níveis de raciocínio low, medium, high (padrão) e xhigh; o raciocínio não pode ser desligado. A API também oferece function calling, saídas estruturadas, busca na web, busca no X e execução de código.

Nosso overview do Grok 4.7 cobre o lançamento e os benchmarks. A SpaceXAI marca Chat Completions como legado, então todos os exemplos aqui usam a Responses API.

Quanto custa o Grok 4.7?

Abaixo de 200.000 tokens de prompt, o Grok 4.7 custa US$ 2 por milhão de tokens de entrada, US$ 0,50 por milhão de tokens de entrada em cache e US$ 6 por milhão de tokens de saída. Quando um prompt chega a 200.000 tokens, cada token daquele pedido é faturado a US$ 4, US$ 1 e US$ 12.

Ferramentas no servidor têm tarifas separadas: a página de preços cobra US$ 5 por 1.000 chamadas de busca na web ou execução de código. Buscas em documentos anexados custam um centavo cada, e documentos armazenados também têm cobrança diária por GiB. Use um prompt_cache_key estável para requisições relacionadas, mas preveja entrada sem cache no orçamento.

Leia o custo faturado em usage.cost_in_usd_ticks. A documentação de controle de custos diz que inclui cache e cobranças de ferramentas. Divida o valor por 10^10 para obter dólares.

Por que testar o Grok 4.7 em projeto de circuito?

Projeto de circuito testa leitura de documentos, cálculos, uso de ferramentas e verificação em uma única tarefa. A SpaceXAI reporta 64,0% para o Grok 4.7 no EEBench. A metodologia do EEBench usa simulações e checagens de BOM (lista de materiais) em vez de um LLM juiz, e o EnviroNode segue a mesma lógica.

O que vamos construir: a revisão do circuito EnviroNode Rev A

O EnviroNode Rev A é um nó de sensores alimentado por USB. Você pode baixar o projeto completo no GitHub.

O diagrama traz todos os valores de componentes de que o Grok precisa para a revisão. Cada requisito tem um ID como PWR-002 ou BW-001, assim cada achado aponta para uma regra.

Esquemático do EnviroNode Rev A com valores. Imagem do autor.

Antes de o Grok revisar a placa, exponha todas as regras que o verificador vai usar. A função retorna cinco checagens de aprovado-ou-reprovado baseadas nestes oito requisitos:

• PWR-001: Entrada USB fica entre 4,75 V e 5,25 V
• PWR-002: O regulador cobre a carga de pico
• PWR-003: Cargas fora do MCU usam orçamento de 10 mA
• SIG-001: Escala total do sensor é 1,0 V
• ADC-001: Entrada do ADC fica em ou abaixo de 2.250 mV
• ADC-002: Entrada do ADC atinge pelo menos 1.500 mV
• BW-001: Sinais até 100 Hz perdem menos de 1 dB
• BW-002: O cutoff do filtro fica em ou abaixo de 500 Hz

O modelo recebe o mesmo conjunto de requisitos. Nenhum limite do verificador aparece só depois que o Grok propõe uma correção.

Quais são os três defeitos inseridos?

Três falhas podem ser checadas com números. A contagem fica fora do prompt.

• Regulador subdimensionado (PWR-002): o TI TLV700 é especificado para 200 mA, enquanto o datasheet do ESP32-C3 lista pico de transmissão Wi-Fi de 335 mA e a checklist de esquemático da Espressif pede pelo menos 500 mA.

• ADC acima da faixa (ADC-001): um ganho de 3 coloca 3,0 V no ADC, mas a faixa efetiva do datasheet vai até 2.500 mV, e o requisito permite 90% disso.

• Filtro lento demais (BW-001): 10 kΩ e 1 µF dão cutoff de 15,9 Hz, enquanto sinais até 100 Hz podem perder no máximo 1 dB.

O defeito do ADC diz respeito à faixa de medição, não a dano de pino. Escolhas corretas, como o resistor do LED e o atraso de CHIP_EN, tornam falsos positivos mensuráveis.

Como funciona o loop de revisão?

A revisão precisa de uma fronteira clara: o Grok propõe mudanças, enquanto o Python decide aprovação ou reprovação. O diagrama mostra onde documentos e ferramentas entram nesse loop.

O loop de revisão separa proposta de verificação. Imagem do autor.

Defina sucesso antes da primeira chamada de API. Conte um defeito apenas quando o Grok o conectar a um requisito e evidência de apoio. Conte uma correção apenas quando verify_design() retornar all_pass = true.

Como configurar a API Grok 4.7 em Python

Você vai precisar de uma chave da API xAI com créditos pré-pagos, Python 3.10 ou superior e o SDK Python da OpenAI apontado para a base URL da xAI. Crie a chave no xAI Console e depois instale os pacotes abaixo.

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  # Diagramas opcionais e testes do verificador

Os exemplos da API usam o primeiro grupo de pacotes; o segundo dá suporte a diagramas do repositório e testes. Testei com Python 3.11.9, openai 3.19.2, pydantic 2.13.5, streamlit 1.64.0 e httpx 0.28.1. Salve a chave na variável de ambiente XAI_API_KEY e carregue com python-dotenv em vez de colocá-la no código-fonte; nosso guia de ambiente virtual explica a configuração caso seja novidade para você.

Faça sua primeira chamada à API Grok 4.7

Se sua chave já funciona com a Responses API, pule para a Etapa 1. Caso contrário, esta requisição checa a chave, a base URL e o ID do modelo de uma vez.

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)

Uma resposta em uma frase significa que a configuração está ok. O timeout longo importa mais adiante, porque requisições com raciocínio e ferramentas podem levar vários minutos.

Etapa 1: o Grok 4.7 consegue revisar um circuito a partir de uma imagem?

Sim, o Grok 4.7 consegue revisar um esquemático só pela imagem, desde que o prompt deixe claro que nenhuma ferramenta será usada. A linha de base envia o PNG como data URL em base64 junto com o texto dos requisitos.

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},
    ]}],
)

O prompt pede três seções: confirmados, precisa de mais evidências e verificados e aceitáveis. Ele não menciona número de defeitos nem componente suspeito.

O que a revisão só por imagem encontrou?

Diga explicitamente ao modelo quando não há ferramentas nem datasheets disponíveis. Caso contrário, ele pode encerrar a resposta dizendo que vai buscar uma especificação à qual não tem acesso.

Como dito no TL;DR, o Grok confirmou o defeito do filtro com cutoff de 15,9 Hz e 16,1 dB de perda em 100 Hz. Colocou regulador e ADC em "precisa de mais evidências" em vez de chutar seus limites.

Etapa 2: como adicionar datasheets com a Files API

Documentos anexados transformam uma preocupação vaga em uma afirmação sustentada por números. Faça upload de cada documento uma vez e referencie por 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}]

Como este tutorial define expires_after para sete dias, IDs em cache só valem nesse período. Sem expires_after, a xAI mantém os arquivos enviados até você excluí-los.

Nas respostas do SDK da OpenAI capturadas aqui, a busca em anexos apareceu como itens custom_tool_call chamados pdf_search e pdf_browse, enquanto o uso contou em document_search_calls. Isso é comportamento observado, não o contrato geral de tipos de ferramenta, então o loop também checa o contador documentado.

Como os datasheets mudam a revisão?

Os documentos resolveram as duas dúvidas da Etapa 1 e sustentaram os achados de energia, ADC e filtro. O achado do regulador citou a especificação de 200 mA do TLV700, o pico de 335 mA do ESP32-C3 e a recomendação de fornecimento de 500 mA.

Para o filtro, o Grok calculou quais valores de capacitor atenderiam às duas regras de banda mantendo R5 inalterado: cerca de 32 a 81 nF. Todo decoy caiu em "verificado e aceitável" com justificativa.

Etapa 3: como verificar cálculos com execução de código do Grok 4.7

Code execution é o sandbox de Python no servidor da xAI, adicionado em tools como {"type": "code_interpreter"} quando você usa o cliente da OpenAI. O prompt adiciona uma regra: toda afirmação com número precisa ser calculada antes de contar como confirmada.

O guia de execução de código linkado antes diz que o sandbox não tem acesso à rede e não mantém estado entre requisições. Para alguns números de datasheet, isso é suficiente.

Quais cálculos o Grok deve conferir?

Peça ao Grok para conferir orçamento de energia, faixa do ADC e banda do filtro em um único script. Se circuitos não são sua praia, pule a saída abaixo; o essencial vem a seguir.

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

O cutoff mínimo de 196,5 Hz é o número de que depende a correção do filtro, e o código o calcula em vez de deixar para a aritmética do modelo. Mesmo no canto de tolerância com menor atenuação, a perda passa de 15 dB em 100 Hz, então o veredito se mantém.

Etapa 4: o Grok 4.7 consegue buscar na web via API?

Sim. A busca na web checa se os documentos anexados ainda estão atuais, já que fabricantes revisam datasheets após o cutoff de treinamento do modelo. Restrinja a domínios oficiais para manter as evidências de primeira mão.

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

O guia de busca na web linkado antes permite até cinco allowed_domains, incluindo subdomínios como docs.espressif.com. Eu manteria esta etapa mesmo quando os datasheets anexados forem os mais recentes, pois ela pode pegar uma revisão publicada após seu upload.

O que as citações comprovam?

O Grok deve citar a página atual do produto da TI, a documentação do ESP32-C3, a checklist de hardware e quaisquer erratas relevantes. Trate essas citações como evidência da fonte, não como prova de que a conclusão de engenharia está correta.

Filtros de domínio ainda podem retornar uma página irrelevante. Verifique se cada citação respalda exatamente o componente e o limite usados no cálculo.

Grok busca em arquivos, calcula, checa fontes. Imagem do autor.

Etapa 5: como adicionar um verificador com function calling do Grok 4.7

verify_design() é uma função Python simples que roda na sua máquina e é a única juíza de aprovação de uma revisão. O Grok propõe valores de projeto via function calling, e a função os confere contra limites fixos.

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"],
    },
}

A capacidade de potência deve atender a max((335 + 10) mA × 1.25, 500 mA). Para o ADC, 1.0 V × (1 + Rf/Rg) deve ficar entre 1.500 e 2.250 mV. Checagens do filtro medem a perda em 100 Hz e limitam o cutoff a 500 Hz; cada checagem retorna valor, limite e aprovado ou reprovado.

O schema da ferramenta só diz ao Grok quais valores enviar. A lógica central de aprovado ou reprovado é Python comum:

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}

A função completa também rejeita valores inválidos e retorna medições com cada resultado. Teste com um projeto conhecido como bom, um conhecido como ruim, um componente desconhecido e um caso no limite.

Por que o código, e não o modelo, deve dar a nota da correção?

Mantenha especificações de componentes fora do controle do modelo. Eu não deixaria o modelo fornecer sua própria corrente nominal. O Grok envia um part number e a função consulta a especificação no catálogo do aplicativo.

Um agente não deve propor a solução e decidir se ela está correta quando o código pode checar a resposta. Substitua verify_design() por uma suíte de testes ou checagem de schema quando a tarefa mudar. Escrever o verificador dá trabalho extra, mas o resultado de aprovado ou reprovado não depende da opinião do modelo.

Etapa 6: como redesenhar e verificar o circuito

Dê ao Grok um objetivo: corrigir cada violação confirmada com o menor conjunto razoável de mudanças e não dar o projeto como concluído até a checagem definida antes passar. Forneça as evidências e ferramentas das Etapas 3 a 5 e defina um limite de requisições.

É aqui que o aviso de contexto do TL;DR importa. Resolva isso antes de adicionar mais turnos.

Por que loops pesados em arquivos precisam de compactação de contexto?

Uma continuação inclui resultados de ferramentas anteriores, e buscas em documentos podem retornar muito texto. No protótipo que falhou, a próxima continuação chegou a 1.116.321 tokens e excedeu a janela de 500.000 do Grok 4.7.

Context compaction não salva uma requisição que já estourou o limite. O loop corrigido compacta cada turno com busca em documento antes de enviar o próximo pedido.

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)  # passe o item de compactação de volta sem alterações
    # A compactação descarta a saída das ferramentas, então reafirmamos o veredito do verificador.
    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)

Mantenha esse último append. A compactação descarta saídas verbosas de ferramentas, então reafirmar o resultado do verificador ajuda a próxima resposta a evitar checagens inventadas ou confusas. Compactar após cada turno pesado em documentos é um ritmo conservador; um sistema maior pode usar um limiar de tokens de entrada.

A Rev B passou na verificação?

Sim. O Grok trocou um componente em cada subsistema que falhou: energia, ganho do ADC e banda do filtro. O diagrama mostra exatamente os valores da Rev A e Rev B.

Três trocas de componentes corrigem a Rev A. Imagem do autor.

Os valores revisados então vão para verify_design(). Ela retorna um resultado para cada requisito.

Projeto revisado passa em todas as checagens. Imagem do autor.

Um resultado de falha volta como function_call_output, então o Grok pode revisar o projeto até as checagens passarem ou o limite de requisições ser atingido.

Etapa 7: como retornar uma revisão estruturada do circuito

Structured outputs retornam um objeto que bate com um schema em vez de um texto que você teria que fazer parsing. Chame client.responses.parse() com um modelo Pydantic na mesma conversa, com chamadas de ferramenta desligadas.

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,
)

Um schema válido não prova que o conteúdo está certo, então inclua os resultados do verificador e diga ao Grok para basear verifier_result neles. O JSON pode alimentar um tracker de issues ou uma fila de aprovação humana.

O que o relatório estruturado trouxe?

O relatório estruturado deve marcar cada defeito original como resolvido, citar o valor medido retornado pelo verificador e manter preocupações não testadas em open_risks. Para este projeto, essas preocupações incluem um regulador exatamente no piso de 500 mA e um capacitor do ADC diferente da recomendação da Espressif.

Esforço de raciocínio mais alto no Grok 4.7 melhora a revisão?

Esforço maior não melhorou a pontuação do verificador, mas mudou a qualidade da correção do filtro. Cada nível recebeu o mesmo esquemático, prompt, ferramentas e limite de requisições.

low reduziu o resistor e manteve o capacitor de 1 µF, deixando comportamento com carga capacitiva e tempo de assentamento fora do verificador. A orientação da Microchip sobre cargas capacitivas diz que um resistor em série pode melhorar a estabilidade, então esse resultado não prova que a correção é instável; ele pede testes de resposta em frequência, resposta a degrau ou de bancada. high trocou o capacitor, enquanto xhigh escolheu os mesmos valores finais de high após uma chamada extra ao verificador.

Quando vale a pena usar xhigh?

Nesta comparação única, high deu o melhor equilíbrio. Evitou a preocupação com carga não modelada sem a chamada extra ao verificador feita por xhigh. Uma execução por nível não estabelece ranking geral.

O Grok 4.7 corrigiu o circuito?

A resposta à pergunta inicial é sim, dentro das cinco checagens do verificador. A tabela condensa os achados anteriores em uma visão.

• Imagem e requisitos
  • Adiciona: inspeção visual
  • Resultado: confirma o que o esquemático sozinho pode provar
• Datasheets
  • Adiciona: limites do fabricante
  • Resultado: converte duas dúvidas em achados
• Execução de código
  • Adiciona: cálculos conferidos
  • Resultado: mede os problemas de energia e filtro
• Busca na web
  • Adiciona: fontes oficiais atuais
  • Resultado: checa se a evidência anexada está atualizada
• Verificador local
  • Adiciona: aprovado ou reprovado em Python
  • Resultado: aceita só uma revisão que passa em todas as regras

O Grok corrigiu os requisitos codificados. Ele não provou que a placa revisada estava eletricamente completa ou pronta para produção.

Documentos decidem se uma preocupação tem evidência. Python decide se uma revisão passa. Prosa fluente não substitui nenhum dos dois.

Veja a revisão no Streamlit

Nosso guia de Streamlit explica a interface usada aqui. Ele usa streaming para mostrar chamadas de ferramenta conforme chegam e, depois, exibir as checagens do verificador e o relatório final.