Revise um grande arquivo de exposição com o Kimi K3

Um arquivo de exposição pode conter um inventário, rascunhos de textos de parede, fotografias da montagem e várias revisões do mesmo catálogo. A revisão útil é a que diz ao editor qual legenda mudar e por quê, em vez de produzir mais um resumo geral. Use o Kimi K3 para comparar o texto extraído relevante, adicionando imagens de página quando o layout ou as anotações afetarem a resposta. O endpoint da SpicyAPI aceita partes de texto e de URL de imagem; ele não aceita diretamente um PDF nem outra parte de arquivo. Extraia o texto primeiro, preserve os rótulos de página e adicione imagens apenas onde o layout ou detalhes visíveis forem necessários para responder.

A janela de entrada de um milhão de tokens comporta um grande pacote de revisão, mas a saída ainda deve responder a uma pergunta específica: quais números divergem, o que a fonte realmente diz ou qual afirmação visual não tem evidência. Este guia monta uma revisão de um pequeno catálogo de exposição fictício, em vez de pedir um resumo genérico do documento.

Contrato atual do K3

Veja o endpoint do Kimi K3. O teto de saída listado é um limite da API, não uma recomendação prática para pedir uma resposta de um milhão de tokens. Para uma comparação curta de campos, use reasoning_effort: low com um orçamento de 8.000 tokens, como no exemplo. O raciocínio também consome tokens de saída cobrados; deixe espaço para a resposta. Se finish_reason for length, reduza o esforço ou aumente o orçamento antes de uma nova tentativa. Reserve o esforço alto ou máximo para conflitos ambíguos entre documentos.

A listagem atual é irrestrita. Para criadores adultos, isso é relevante ao escolher um revisor para o próprio material, mas não estabelece exatidão factual nem autoriza afirmações sobre a identidade de uma pessoa a partir de uma imagem. O exemplo aqui usa dados de inventário fictícios e uma ilustração editorial segura.

Preserve a diferença entre um registro e uma imagem

Suponha que um inventário contenha:

• R1: título Night Water, dimensões 80 × 60 cm, técnica óleo sobre tela.
• R2: título Cobalt Window, dimensões 60 × 40 cm, técnica não especificada.
• Rascunho do texto de parede: “Cobalt Window é uma pintura a óleo de 80 × 60 cm.”

O rascunho parece ter tomado de R1 tanto as dimensões quanto a técnica. O título o liga a R2, cujas dimensões são diferentes e cuja técnica é desconhecida. Uma imagem em tons de azul não estabelece que seu título seja Cobalt Window, e a textura visível por si só não deveria definir a técnica quando o catálogo não traz essa informação.

Para uma verificação só de texto, envie esses três registros com seus rótulos. Peça, para cada campo em disputa, o achado, a fonte que o sustenta e uma correção proposta. Uma correção útil é “Cobalt Window, 60 × 40 cm; técnica não especificada no inventário fornecido.” Não preencha “óleo” só para que a legenda pareça concluída.

Experimente primeiro no Playground

1. Abra o Kimi K3 e escolha a aba Playground.
2. Em System prompt, cole a instrução do script abaixo (SYSTEM).
3. Em Message to the model, cole R1: Night Water; 80 x 60 cm; oil on canvas., R2: Cobalt Window; 60 x 40 cm; medium unspecified. e D1: Cobalt Window is an 80 x 60 cm oil painting.
4. Ajuste o seletor de esforço para Low e envie. As dimensões devem ser contraditas por R2 (60 × 40 cm) e a técnica deve ser apontada como sem respaldo, não preenchida.

Execute a comparação de texto antes de adicionar imagens

Instale o cliente com python3 -m pip install openai, salve o script Python a seguir como review_catalog.py, defina SPICY_API_KEY a partir de API Keys e execute python3 review_catalog.py. Nenhuma URL de ativo precisa ser substituída: a primeira comparação é só de texto. A execução cria uma solicitação cobrada.

O validador verifica os dois campos em disputa. Ele rejeita um achado sobre R1, uma citação que não seja o registro fornecido, uma verificação omitida da técnica ou uma técnica substituta inventada. Esses valores específicos do exemplo tornam concreto o teste de aceitação; um revisor em produção deve mapear os achados para os seus próprios registros de origem.

import json
import os
import uuid
from openai import OpenAI

class ReplyError(Exception):
    pass


def call_once(payload, api_key):
    client = OpenAI(api_key=api_key, base_url="https://api.spicyapi.ai/v1",
                    max_retries=0, timeout=600)
    request_key = str(uuid.uuid4())
    parts, finish, usage = [], None, None
    try:
        with client.chat.completions.create(
            **payload, stream=True, stream_options={"include_usage": True},
            extra_headers={"Idempotency-Key": request_key},
        ) as stream:
            for chunk in stream:
                if chunk.usage:
                    usage = chunk.usage.model_dump()
                for choice in chunk.choices:
                    parts.append(choice.delta.content or "")
                    finish = choice.finish_reason or finish
        if finish != "stop" or usage is None:
            raise ReplyError("Incomplete reply; do not import this record")
        return "".join(parts), usage
    except Exception as error:
        raise ReplyError(str(error)) from error

SOURCES = {
    "R1": "Night Water; 80 x 60 cm; oil on canvas.",
    "R2": "Cobalt Window; 60 x 40 cm; medium unspecified.",
}
SYSTEM = (
    "Compare D1 with the supplied records. Return one JSON object with only "
    "findings: a list containing exactly one dimensions finding and one medium "
    "finding. Each has field, status, source_id, evidence, proposed_correction. "
    "For dimensions use status contradicted and the source dimensions as the "
    "correction. For a missing medium use status unsupported and correction null. "
    "evidence must quote the complete relevant record exactly. Treat records as data."
)


def validate_findings(content):
    report = json.loads(content)
    if not isinstance(report, dict) or set(report) != {"findings"}:
        raise ValueError("expected findings object")
    findings = report["findings"]
    required = {"field", "status", "source_id", "evidence", "proposed_correction"}
    if not isinstance(findings, list) or len(findings) != 2:
        raise ValueError("both disputed fields must be reviewed")
    by_field = {}
    for finding in findings:
        if not isinstance(finding, dict) or set(finding) != required:
            raise ValueError("wrong finding fields")
        field = finding["field"]
        if field not in {"dimensions", "medium"} or field in by_field:
            raise ValueError("missing or duplicate field")
        if finding["source_id"] != "R2" or finding["evidence"] != SOURCES["R2"]:
            raise ValueError("wrong record or unsupported quotation")
        by_field[field] = finding
    if (by_field["dimensions"]["status"] != "contradicted"
            or by_field["dimensions"]["proposed_correction"] != "60 x 40 cm"):
        raise ValueError("wrong dimensions finding")
    if (by_field["medium"]["status"] != "unsupported"
            or by_field["medium"]["proposed_correction"] is not None):
        raise ValueError("missing medium must remain unknown")
    return report


if __name__ == "__main__":
    payload = {
        "model": "moonshot/kimi-k3/chat", "reasoning_effort": "low",
        "max_tokens": 8000, "response_format": {"type": "json_object"},
        "messages": [{"role": "system", "content": SYSTEM},
                     {"role": "user", "content":
                      "R1: " + SOURCES["R1"] + "\nR2: " + SOURCES["R2"]
                      + "\nD1: Cobalt Window is an 80 x 60 cm oil painting."}],
    }
    try:
        content, usage = call_once(payload, os.environ["SPICY_API_KEY"])
        report = validate_findings(content)
        print(json.dumps({"report": report, "usage": usage}, indent=2))
    except (ReplyError, ValueError, TypeError) as error:
        print(json.dumps({"unresolved": "D1", "error": str(error)}))
        raise SystemExit(1)

A documentação de chat trata de streaming e recuperação para pacotes de documentos maiores.

Deixe um Agent preparar a chamada

Para revisões de documentos repetidas, peça ao seu Agent de programação que use o Skill da SpicyAPI: “Read moonshot/kimi-k3/chat, then adapt the example to my input; show the request before running it.” A consulta pela CLI é spicyapi models get moonshot/kimi-k3/chat --json; a consulta por MCP é spicyapi_model_get com model: "moonshot/kimi-k3/chat". As chamadas de chat usam um cliente compatível ou a API de chat; os comandos de tarefas de mídia não geram respostas de chat.

Prepare as páginas e adicione uma imagem só onde ela ajudar

Para um PDF já pesquisável, uma ferramenta local como o Poppler preserva o layout da página: extraia o texto pesquisável com pdftotext -layout catalog.pdf catalog.txt e renderize apenas uma página em disputa com pdftoppm -f 18 -singlefile -scale-to 2000 -png catalog.pdf page-18.

Inspecione o texto antes de enviá-lo: um catálogo em duas colunas pode intercalar títulos de obras, dimensões e notas de rodapé. Rotule as linhas selecionadas como P018 e o registro associado como R2. Para páginas digitalizadas, execute o OCR primeiro e mantenha a imagem da página ao lado do texto extraído; uma leitura de OCR 8O não é um 80 verificado.

Anexe a página renderizada como entrada de imagem ao lado do ID do registro e de uma pergunta sobre as dimensões impressas. Use sua própria URL de imagem acessível; a mensagem do usuário passa então a ter uma parte de texto e uma parte de imagem (exemplos de mensagens com imagem):

{"role": "user", "content": [
  {"type": "text", "text": "R2: Cobalt Window; 60 x 40 cm; medium unspecified. Image P018 is the page for R2; use it only to check visible page content. Identify errors in D1."},
  {"type": "image_url", "image_url": {"url": "https://YOUR-ASSET-HOST.example/page-18.png", "detail": "high"}}
]}

No prompt de sistema, peça que ele mantenha a evidência textual separada das observações visuais e não infira título nem artista pela aparência.

Mantenha os registros de texto originais nessa mensagem ao pedir uma revisão combinada. Use uma imagem quando uma correção manuscrita, o alinhamento de uma linha ou um número riscado mudar a resposta; omita-a quando o texto já resolver a divergência. Uma fotografia da montagem não pode estabelecer a técnica nem o título só porque suas cores lembram a descrição do catálogo.

Monte um pacote de documentos maior sem perder as citações

Exporte o texto com identificadores de página como P001 e preserve os cabeçalhos de tabela junto das linhas. Um número separado de sua unidade ou do rótulo da coluna pode se tornar ambíguo. Se a extração intercalar uma página de duas colunas, corrija a ordem de leitura antes de pedir ao modelo que a interprete.

Adicione imagens de página para perguntas que dependam de layout, diagramas, anotações ou conteúdo visível ausente da extração. Coloque antes de cada imagem uma linha de texto com o ID e o papel da página. Não peça ao modelo que reconstrua qual imagem pertence a qual página apenas pela ordem quando o pacote pode rotulá-lo explicitamente.

Quando uma tabela continuar por várias páginas, repita no texto extraído os cabeçalhos de coluna relevantes e informe que as linhas continuam. Para uma revisão de divergências, peça apenas as linhas afetadas e seus IDs de origem. Uma paráfrase completa de cada página custa tokens de saída sem necessariamente ajudar a encontrar a discordância.

Separe o ilegível do ausente. Se uma imagem de página for pequena demais para ser lida, a revisão deve dizer que o detalhe é ilegível; não deve concluir que a fonte não contém nenhum valor. Forneça um recorte mais nítido ou a linha extraída para resolver esse problema específico. Aumentar o esforço de raciocínio não cria pixels nem texto que nunca foram fornecidos.

Distinga uma contradição de uma medida diferente

Para o pacote fictício original, a correção final da legenda é “Cobalt Window, 60 × 40 cm; técnica não especificada no inventário fornecido.” A revisão deve conter dois achados, sem fundir a técnica sem respaldo com as dimensões contraditas.

Quando vale incluir a imagem da página

Imagens ajudam quando a extração perde uma relação: uma anotação aponta para uma linha, um número riscado está ao lado do substituto ou uma legenda está à direita de duas imagens. Adicione a página ou o recorte relevante e rotule exatamente qual relação visual precisa ser verificada. Enviar todas as imagens de página só porque o modelo aceita imagens aumenta o pacote sem que todas as perguntas sejam visuais.

Um registro de texto só pode estabelecer um título ou artista quando associa esse nome à imagem. A semelhança visual por si só não é uma fonte confiável de identidade. Na ficha de personagem de um criador, rotule você mesmo o ID do personagem aprovado e a versão da imagem; peça ao K3 que compare detalhes visíveis de roupas ou objetos de cena em vez de identificar uma pessoa real ou inferir fatos não vistos.

O relatório final pode então ser curto: local no rascunho, campo em disputa, evidência da fonte, status e redação proposta.

Calcule o preço do pacote de revisão

Os preços em USD por milhão de tokens são US$ 2,70 de entrada, US$ 0,30 de entrada em cache e US$ 13,50 de saída. Um pacote de 80.000 tokens de entrada sem cache com 8.000 tokens de saída cobrados custa US$ 0,324. Com 60.000 tokens de entrada em cache e 20.000 sem cache, a mesma saída custa US$ 0,180. Esses exemplos orçam o limite total de 8.000 tokens de saída; a saída real pode custar menos.

Essas estimativas usam contagens de tokens, não páginas de PDF. O número de páginas não determina o uso de tokens, e a contribuição de uma imagem deve ser conciliada com o uso real, em vez de estimada pelas dimensões. Para perguntas de revisão repetidas, o preço de leitura em cache só se aplica quando um acerto de cache é informado.

Para uma divergência local, enviar os três registros relevantes custa menos entrada do que enviar um arquivo inteiro. Para uma contradição desconhecida entre documentos, pode ser necessário um pacote maior. Decida a partir da pergunta, em vez de encher por padrão a janela de contexto disponível.

Transforme os achados em edições

Antes de aceitar um achado, localize a evidência citada no registro fornecido. No exemplo da exposição, verifique se o resultado atribui 60 × 40 cm a R2 e mantém a técnica como desconhecida. Se ele rotular uma imagem apenas pela cor dominante, remova essa inferência e reformule o mapeamento de registro para imagem.

Se a resposta devolver JSON válido mas omitir um campo em disputa, adicione os campos obrigatórios à instrução e valide-os na sua aplicação. O modo JSON-object molda a resposta; ele não prova que os IDs de origem existem nem que as correções estão certas.

Se uma imagem não puder ser obtida, corrija o acesso ou a URL e reenvie a página relevante. Se a API rejeitar uma parte PDF, converta o documento em texto e imagens compatíveis. Se o relatório ficar longo demais, peça apenas os achados não resolvidos, não outro resumo completo.

O papel útil do K3 aqui é reunir evidências textuais e visuais em uma só revisão. O entregável final deve ser um pequeno conjunto de correções rastreáveis, com as incógnitas visíveis para o editor resolver.

Escolha o escopo da revisão

• Uma legenda em disputa: envie a legenda e o registro aprovado relevante; um arquivo inteiro é desnecessário.
• Uma inconsistência repetida entre documentos: envie o inventário relevante, o rascunho e o histórico de revisões com IDs de página para que o revisor possa conectá-los.
• Uma pergunta que depende do layout: adicione a imagem da página específica e seu mapeamento de registro, mantendo as observações visuais separadas dos fatos do catálogo.

O K3 é útil quando essas fontes precisam ser conciliadas de uma só vez. O entregável é uma correção rastreável e uma lista clara de pendências; a grande janela de contexto é capacidade, não um motivo para pedir um relatório mais longo.