Mostre à IA alguns exemplos da estrutura exata de saída desejada e depois valide o JSON retornado antes de utilizá-lo. Um pequeno conjunto de tickets sintéticos demonstra como exemplos de formatação e verificações automáticas funcionam em conjunto.
A tradução foi feita com IA. Confira o código, as unidades e os valores junto com o original. A revisão por falantes nativos de cada idioma ainda não foi concluída. English
Para quem éEste guia é voltado a pessoas que usam IA para transformar itens de trabalho repetitivos e precisam de uma saída previsível e legível por máquina em vez de texto livre.
Suponha que você queira que uma IA transforme tickets curtos de suporte em registros estruturados. Cada resultado deve conter exatamente quatro chaves: ticket_id, priority, owner_team e action. priority pode ser LOW, MEDIUM ou HIGH. owner_team pode ser IT, FACILITIES ou FINANCE. Todos os quatro valores devem ser strings não vazias.
A ideia importante é definir o formato independentemente da resposta da IA. A IA produz um registro candidato. Seu script decide se esse candidato atende à estrutura exigida.
Os tickets a seguir são sintéticos e foram escritos especificamente para este artigo. Eles são deliberadamente simples para que você possa determinar manualmente o resultado estruturado pretendido.
| ticket_id | Texto do ticket sintético | Classificação esperada |
|---|---|---|
| T101 | A planilha de folha de pagamento não pode ser aberta antes do processamento de pagamentos de hoje. | HIGH · FINANCE |
| T102 | A luz da sala de reuniões B está piscando, mas a sala ainda pode ser usada. | LOW · FACILITIES |
| T103 | O notebook do novo funcionário não consegue se conectar ao Wi-Fi do escritório. | MEDIUM · IT |
Neste tutorial, as ações esperadas também são definidas antecipadamente: T101 deve ser Check payroll workbook access, T102 deve ser Inspect meeting room B light e T103 deve ser Troubleshoot laptop Wi-Fi connection. Esses valores esperados fazem parte do exercício sintético e não são regras gerais para operações reais de suporte.
Um prompt few-shot inclui um ou mais exemplos concluídos antes das novas entradas. As demonstrações abaixo mostram tanto o estilo de classificação quanto o formato exato do JSON. Elas usam tickets sintéticos diferentes dos três itens que serão verificados.
Convert each ticket into a JSON object.
Rules:
- Return one JSON array only.
- Do not add explanations or Markdown.
- Use exactly these keys in every object: ticket_id, priority, owner_team, action.
- priority must be LOW, MEDIUM, or HIGH.
- owner_team must be IT, FACILITIES, or FINANCE.
Example 1 input:
Ticket ID: E001
Text: Printer on floor 2 is out of paper.
Example 1 output:
{"ticket_id":"E001","priority":"LOW","owner_team":"IT","action":"Refill or check floor 2 printer"}
Example 2 input:
Ticket ID: E002
Text: Expense approval file is unavailable before today's reimbursement deadline.
Example 2 output:
{"ticket_id":"E002","priority":"HIGH","owner_team":"FINANCE","action":"Check expense approval file access"}
Now process these tickets:
T101: Payroll spreadsheet cannot be opened before today's payment run.
T102: Meeting room B light is flickering but the room is still usable.
T103: New employee laptop cannot connect to the office Wi-Fi.
Os exemplos mostram mais do que nomes de campos. Eles demonstram valores de categoria em maiúsculas, frases curtas de action, strings JSON entre aspas e ausência de comentários ao redor. Isso reduz a ambiguidade sobre como a resposta deve ser apresentada.
Para este exercício sintético, a resposta esperada é o array JSON abaixo. Salve a resposta real da IA como ai_output.json antes de executar o verificador. Não edite silenciosamente uma resposta malformada antes; o objetivo do verificador é revelar se a resposta original seguiu o contrato.
[
{
"ticket_id": "T101",
"priority": "HIGH",
"owner_team": "FINANCE",
"action": "Check payroll workbook access"
},
{
"ticket_id": "T102",
"priority": "LOW",
"owner_team": "FACILITIES",
"action": "Inspect meeting room B light"
},
{
"ticket_id": "T103",
"priority": "MEDIUM",
"owner_team": "IT",
"action": "Troubleshoot laptop Wi-Fi connection"
}
]
Deve haver exatamente 3 objetos e 12 valores de campo no total. Cada uma das três prioridades permitidas aparece uma vez, e cada uma das três equipes proprietárias permitidas aparece uma vez.
Salve o script a seguir como check_ai_output.py. Ele valida a sintaxe JSON, o comprimento do array, as chaves exatas, os tipos de dados, os valores de categoria permitidos, os IDs dos tickets e as classificações sintéticas esperadas. Ele grava um CSV de revisão somente depois de interpretar a resposta da IA.
import csv
import json
from pathlib import Path
SOURCE = Path("ai_output.json")
OUTPUT_DIR = Path("outputs") / "few_shot_check_result"
REPORT = OUTPUT_DIR / "format_check.csv"
EXPECTED = {
"T101": ("HIGH", "FINANCE", "Check payroll workbook access"),
"T102": ("LOW", "FACILITIES", "Inspect meeting room B light"),
"T103": ("MEDIUM", "IT", "Troubleshoot laptop Wi-Fi connection"),
}
REQUIRED_KEYS = {"ticket_id", "priority", "owner_team", "action"}
PRIORITIES = {"LOW", "MEDIUM", "HIGH"}
TEAMS = {"IT", "FACILITIES", "FINANCE"}
def main() -> None:
if not SOURCE.is_file():
raise FileNotFoundError(f"AI output not found: {SOURCE}")
if OUTPUT_DIR.exists():
raise FileExistsError(f"Output folder already exists: {OUTPUT_DIR}")
with SOURCE.open("r", encoding="utf-8") as stream:
data = json.load(stream)
if not isinstance(data, list):
raise ValueError("Top-level JSON value must be an array.")
if len(data) != len(EXPECTED):
raise ValueError(f"Expected {len(EXPECTED)} objects, got {len(data)}.")
rows = []
seen = set()
for index, item in enumerate(data, start=1):
errors = []
if not isinstance(item, dict):
raise ValueError(f"Item {index} is not a JSON object.")
if set(item) != REQUIRED_KEYS:
errors.append("keys")
for key in REQUIRED_KEYS:
if key not in item or not isinstance(item.get(key), str) or not item.get(key).strip():
errors.append(f"invalid_{key}")
ticket_id = item.get("ticket_id", "")
if ticket_id in seen:
errors.append("duplicate_ticket_id")
seen.add(ticket_id)
if item.get("priority") not in PRIORITIES:
errors.append("priority")
if item.get("owner_team") not in TEAMS:
errors.append("owner_team")
expected = EXPECTED.get(ticket_id)
if expected is None:
errors.append("unexpected_ticket_id")
else:
actual = (
item.get("priority"),
item.get("owner_team"),
item.get("action"),
)
if actual != expected:
errors.append("content_mismatch")
rows.append({
"item": index,
"ticket_id": ticket_id,
"status": "PASS" if not errors else "FAIL",
"errors": ";".join(errors),
})
missing_ids = set(EXPECTED) - seen
if missing_ids:
raise ValueError(f"Missing ticket IDs: {sorted(missing_ids)}")
OUTPUT_DIR.parent.mkdir(parents=True, exist_ok=True)
OUTPUT_DIR.mkdir()
with REPORT.open("x", encoding="utf-8", newline="") as stream:
writer = csv.DictWriter(
stream,
fieldnames=["item", "ticket_id", "status", "errors"],
)
writer.writeheader()
writer.writerows(rows)
failures = sum(row["status"] == "FAIL" for row in rows)
print(f"Objects checked: {len(rows)}.")
print(f"Passed: {len(rows) - failures}; failed: {failures}.")
print(f"Report: {REPORT.as_posix()}")
if failures:
raise RuntimeError("AI output failed one or more checks.")
if __name__ == "__main__":
main()
Se ai_output.json corresponder exatamente à saída sintética esperada, todos os 3 objetos devem passar. O texto esperado do console abaixo foi derivado manualmente e não é um log de execução.
Objects checked: 3.
Passed: 3; failed: 0.
Report: outputs/few_shot_check_result/format_check.csv| Problema | O que o verificador deve revelar |
|---|---|
| A IA adiciona uma explicação antes do JSON | json.load falha porque o arquivo não é um único valor JSON válido. |
| Um objeto usa urgency em vez de priority | A verificação de chaves exatas falha. |
| priority é urgent | A verificação de valor permitido falha. |
| T103 aparece duas vezes | A verificação de ID de ticket duplicado falha e outro ID esperado pode estar ausente. |
| A estrutura JSON é válida, mas a classificação está errada | content_mismatch é registrado para este exercício sintético. |
O uso de few-shot melhora a orientação, mas não garante saída determinística. Diferentes sistemas de IA, configurações, contextos ou prompts posteriores podem alterar a resposta. Mantenha o validador mesmo depois de várias execuções bem-sucedidas.
Este exemplo valida deliberadamente um esquema pequeno com verificações em Python escritas manualmente. Esquemas maiores de produção podem se beneficiar de um sistema formal de esquemas e de validação semântica separada. Lembre-se também de que JSON válido é apenas um resultado de formatação: a classificação subjacente ainda pode estar factualmente ou operacionalmente errada.
2026-09-20 · exemplo verificado manualmente · alvo: Python 3.12 · biblioteca padrão: csv, json, pathlib · sem execução
As explicações e os exemplos são de elaboração própria. Os comportamentos e conceitos relacionados podem ser consultados nas fontes oficiais abaixo.