Ganhos:
- Pode descrever a estrutura básica de uma solicitação de API LLM (endpoint, modelo, mensagens, max_tokens)
- Compreende a diferença entre funções de sistema, usuário e assistente e histórico de conversas sem estado
- Pode ler e interpretar campos (blocos de conteúdo, stop_reason, uso) da resposta retornada
Nos módulos anteriores, utilizamos inteligência artificial a partir de uma janela de chat. Mas se você deseja incorporar IA em seu próprio produto, automação ou fluxo de trabalho, uma interface de chat não será suficiente; Você precisa se conectar ao modelo de forma programática, ou seja, com código ou uma ferramenta de automação. O nome dessa ponte é API (Application Programming Interface, o contrato que permite que dois softwares se comuniquem com determinadas regras). Ao concluir esta unidade, você saberá o que constitui uma solicitação de API LLM (Large Language Model), o que as funções de mensagem fazem e como ler a resposta. Esta é a base sobre a qual o restante do módulo será construído.
Como funciona a API?
O fluxo básico da API é este: você envia uma solicitação em um determinado formato; O servidor retorna uma resposta em um formato específico. Em LLMs, geralmente é uma chamada HTTP (HTTP: protocolo padrão para transportar solicitação-resposta na web) para um único endereço (endpoint, o endereço fixo no servidor que trata sua solicitação). Por exemplo, em uma API de mensagens, todas as solicitações vão para um único endereço e são transportadas no corpo como JSON (JavaScript Object Notation — um formato de texto que consiste em pares chave/valor que podem ser lidos por humanos e máquinas).
Em uma solicitação, você especifica pelo menos estas três coisas:
- Modelo: Qual modelo você usará (por exemplo, um modelo rápido e barato ou um modelo poderoso).
- max_tokens: O número máximo de tokens (a menor unidade em que o texto é processado, que será processado detalhadamente na próxima unidade) que o modelo pode produzir; ou seja, limite de saída.
- mensagens: Lista de mensagens que compõem a conversa.
Passo a passo: como configurar uma solicitação
- Prepare o endpoint e as credenciais. Você adiciona sua chave de API (a string secreta que prova sua identidade) à solicitação em um cabeçalho. Você nunca incorpora a chave no código; Abordaremos o armazenamento seguro na unidade 9.
- Selecione o modelo e o limite de saída. Modelo leve + max_tokens pequenos para uma tarefa simples; Modelo poderoso + limite maior para uma tarefa complexa.
- Configure a lista de mensagens. List the system instruction, user message, and past rounds (if any).
- Envie a solicitação e analise a resposta. Leia o conteúdo do texto, o motivo da parada e o uso do token do JSON retornado.
Funções da mensagem: sistema, usuário, assistente
Uma conversa consiste em mensagens organizadas em sequência e cada mensagem tem uma função. A função determina como o modelo trata esse texto.
Função
Quem escreve
Objetivo
sistema
Desenvolvedor/operador
Instruções permanentes, personalidade e regras que se aplicam durante toda a conversa
usuário
usuário final
A pergunta ou entrada atual do usuário
assistente
modelo
Resposta produzida pelo modelo (e respostas anteriores)
A função do sistema está disponível como um campo de sistema separado no corpo da solicitação na maioria dos provedores; usuário e assistente são listados sequencialmente na lista de mensagens. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "Você é um assistente de suporte corporativo. Dê uma resposta curta, formal e verificada. Não invente informações sobre as quais você não tem certeza.", "messages": [ { "role": "user", "content": "Como inicio meu processo de devolução?" } ]}
A fala é apátrida
Aqui está o equívoco mais comum: as chamadas de API LLM não têm estado – o servidor não retém memória entre duas solicitações. A modelo não se lembra da sua solicitação anterior. Se estiver configurando um bate-papo com várias rodadas, você precisará reenviar as rodadas anteriores a cada nova solicitação. A “memória” do modelo consiste em uma lista de mensagens que você enviou.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Olá, meu nome é Deniz." }, { "role": "assistente", "content": "Olá Deniz, em que posso ajudá-lo?" }, { "role": "user", "content": "Acabei de dizer meu nome, você se lembra?" } ]}
Responder corretamente à terceira mensagem depende do envio das duas mensagens anteriores. Se não enviar, a modelo não saberá “Mar” e responderá incorretamente. Isso também afeta diretamente o custo: quanto mais longa a conversa, maior a lista, cada solicitação consumindo mais tokens.
Dica: Em conversas longas, resumir e mover rodadas antigas (resumo + últimas rodadas) em vez de enviar o histórico inteiro reduz custos e preserva a janela de contexto. Iremos aprofundar isso nas unidades 6 e 11.
Leia a resposta
Quando o modelo retorna uma resposta, você recebe um objeto estruturado, não um texto simples. Áreas típicas:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Para iniciar uma devolução, vá para a página 'Meus pedidos' em sua conta..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "output_tokens": 88 }}
- conteúdo: A resposta em si; É uma lista de blocos de conteúdo. O campo de texto do bloco de texto é a resposta real.
- stop_reason: Por que o modelo parou. fim_turno = fim natural; max_tokens = preso no limite de saída (a resposta pode estar incompleta); recusa = recusada por razões de segurança. Seu código deve sempre olhar primeiro para stop_reason.
- uso: números de token de entrada e saída. É a base do rastreamento de custos e limites.
Atenção: Se stop_reason for max_tokens, a resposta não será concluída. Tratar isso como uma “resposta bem-sucedida” e mostrar metade do texto ao usuário é um dos erros mais comuns na produção. Aumente max_tokens ou use streaming.
Alerta fraco / Alerta forte
A mesma tarefa com dois prompts de sistema diferentes:
# FRACOVocê é um assistente. Responda às perguntas.
# FORTEVocê é um assistente de suporte corporativo. Regras:- Confiar exclusivamente nas informações contidas no documento da apólice fornecido; Caso não esteja no documento, diga “Não tenho essa informação, estou encaminhando para a unidade competente”. - As respostas não devem ultrapassar 3 frases, ser formais e claras. - Não solicite dados pessoais (número de identificação do TC, número do cartão) e não repita. - Não adivinhe quando não tiver certeza.
Versão poderosa; Define escopo, forma, margem de segurança e comportamento na incerteza. A consistência do resultado do modelo vem diretamente dessa clareza.
Três Mini Estojos
Caso 1 — Bot de suporte (armadilha de apatridia). Uma equipe de comércio eletrônico colocou o bot no ar; Quando o usuário disse “cancelar o pedido anterior”, o bot “esqueceu” o número do pedido. Motivo: estavam enviando cada solicitação apenas com a última mensagem. Solução: adicionaram as últimas 6 rodadas à lista de mensagens. Resultado: contexto preservado, mas a entrada por solicitação aumentou de 40 tokens para aproximadamente 600 tokens — abordaremos a lição de custo na unidade 2.
Caso 2 — Resumo do contrato incompleto. Uma equipe jurídica estava delineando contratos de 10 páginas; max_tokens: 300 permaneceu baixo, os resumos foram cortados no meio da frase. stop_reason era max_tokens todas as vezes, mas ninguém estava olhando. aumentou max_tokens para 1500 e adicionou verificação stop_reason; A taxa de resumo truncado diminuiu de 18% para 0%.
Caso 3 — Mistura de papéis. Uma equipe de marketing escrevia todas as instruções na mensagem do usuário, deixando o sistema em branco. Quando a entrada do usuário era misturada com a instrução, o modelo às vezes obedecia ao comando do usuário para “esquecer as regras anteriores”. Eles transferiram regras permanentes para o sistema; Ao separar a entrada do usuário da instrução, as violações das regras diminuíram significativamente.
Erros comuns
- Esquecer de enviar o passado: Pensa-se que o modelo “não lembra”; enquanto é apátrida. Você carrega o contexto.
- Não olhando para `stop_reason`: A resposta interrompida com max_tokens é considerada completa.
- Incorporando a instrução em `user`: Regras persistentes no sistema; a entrada instantânea vai para o usuário. A mistura cria vulnerabilidades de segurança.
- Confundindo `content` com uma string simples: a resposta é uma lista de blocos; leia o campo de texto do primeiro bloco de texto, verifique seu tipo antes de obter content[0] com um índice cego.
- Incorporando a chave no código: Use uma variável de ambiente (unidade 9).
Mais profundo: blocos de conteúdo e respostas com várias partes
Entender por que o campo de conteúdo na resposta é uma lista é fundamental para os recursos avançados que você encontrará posteriormente. Às vezes, o modelo não retorna um único bloco de texto, mas vários blocos: um bloco de pensamento, seguido por um bloco de texto; ou um bloco de texto seguido por um bloco de uso de ferramenta. É por isso que contar cegamente o conteúdo[0] como uma "resposta" é frágil. A abordagem correta é percorrer a lista e classificá-la por tipo: você coleta o conteúdo de texto dos blocos cujo campo de tipo é texto e trata os outros tipos (pensamento, ferramenta) separadamente.
O que essa distinção faz na prática é que você pode registrar o raciocínio do modelo (se houver) sem revelá-lo ao usuário, redirecionar as chamadas de ferramenta para uma lógica separada e apenas imprimir a resposta real na tela. À medida que o módulo avança (especialmente nas unidades 4 e 11), você verá como essa estrutura de bloco é útil para validar e direcionar a saída.
Outro ponto prático: você pode acessar o mesmo modelo a partir de diferentes plataformas de provedores (API direta, via provedor de nuvem). Embora o endereço do terminal e o formato de autenticação possam mudar, conceitos básicos como funções de mensagens, ausência de estado e estrutura de resposta permanecem os mesmos. Portanto, os princípios básicos desta unidade se aplicam independentemente da plataforma que você usa.
Em resumo
Uma solicitação de API LLM consiste no modelo, limite de saída e lista de mensagens; funções (sistema, usuário, assistente) determinam o comportamento do modelo. As chamadas não têm estado: você carrega o contexto com cada solicitação. A resposta é um objeto estruturado; Ler e interpretar os campos conteúdo, stop_reason e uso é a base da durabilidade na produção.
Tarefa de aplicativo
Escolha uma tarefa de sua profissão (por exemplo, classificar e-mails recebidos, criar breves resumos). Em um pedaço de papel: (1) escreva o prompt do sistema com 4 a 5 regras, (2) configure um exemplo de mensagem do usuário e um histórico de 2 rodadas, se houver, (3) determine um valor razoável para max_tokens e escreva a justificativa, (4) liste quais valores de stop_reason você tratará na resposta retornada e como.
lista de verificação
- [] Posso contar as três partes obrigatórias de uma solicitação (modelo, max_tokens, mensagens).
- [] Posso explicar a diferença entre funções de sistema, usuário e assistente.
- [ ] Sei que os atendimentos são apátridas e que preciso carregar o passado.
- Posso ler e comentar sobre [] conteúdo, stop_reason e campos de uso.
- [] Com max_tokens posso perceber e lidar com a resposta truncada.