Integrando com os sistemas da empresa: a API local do Ollama

Nesta aula

A tela é para gente. A API é para os seus sistemas.

Até aqui, uma pessoa pergunta e a IA responde. O próximo passo é o sistema perguntar: a planilha de pedidos, o software de atendimento, o fluxo de automação. Para isso existe a API do Ollama, um serviço que já está rodando na sua máquina desde a aula 4, esperando pedidos no endereço localhost:11434. Nesta aula você faz a primeira chamada, entende os dois endpoints que importam, aprende a pedir resposta estruturada e vê três integrações simples que resolvem problema real. Não precisa ser programador: precisa copiar com atenção e ler o que voltou.

• Ao final, você vai fazer uma chamada à API local do Ollama e ler a resposta.
• Vai entender a diferença entre /api/generate e /api/chat, e como pedir JSON.
• Vai sair com um entregável: uma chamada de API funcionando, salva, e a descrição de uma integração para a sua empresa.

O que é a API e por que ela já existe

API é um jeito de um programa falar com outro por mensagens de texto num formato combinado. O Ollama, quando está rodando, escuta em http://localhost:11434 e aceita pedidos num formato chamado JSON: chaves e valores entre chaves e aspas. A interface da aula 5 usa exatamente isso por trás. Você vai usar o mesmo caminho, direto.

Dois endpoints (endereços dentro do serviço) resolvem quase tudo:

Um detalhe importante: por padrão, a API devolve a resposta em pedaços, palavra por palavra, como na tela. Para integração, você quase sempre quer a resposta inteira de uma vez. Isso se pede com "stream": false.

A primeira chamada

Vamos usar o curl, um programa de linha de comando que faz pedidos a endereços web. Ele já vem no macOS e no Linux. No Windows, o Prompt de Comando costuma ter o curl; no PowerShell, o nome curl pode apontar para outro comando com comportamento diferente, então prefira o Prompt de Comando para os exemplos desta aula.

Com /api/generate

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Resuma em uma frase: a loja abre de segunda a sábado, das 8h às 18h, e não abre em feriados.",
  "stream": false
}'

Se o Ollama estiver rodando e o modelo estiver baixado, volta um JSON. O texto da resposta está no campo "response". Junto vêm outros campos, como o tempo total e a quantidade de tokens gerados, úteis para medir velocidade (lembra da aula 6?).

Com /api/chat

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [
    {"role": "system", "content": "Você classifica mensagens de clientes de uma loja de material de construção em uma destas categorias: orcamento, reclamacao, entrega, outro. Responda só com a categoria, em minúsculas, sem ponto."},
    {"role": "user", "content": "Comprei 20 sacos de cimento na terça e até agora não chegou."}
  ],
  "stream": false
}'

Aqui o texto da resposta está em "message", dentro de "content". Repare no papel system: é a instrução fixa da aula 5, agora dentro da chamada. Cada integração pode ter a sua.

Resposta estruturada: JSON que o sistema consegue ler

Para um sistema usar a resposta, ela precisa vir num formato previsível. Texto livre não serve: hoje vem "Categoria: entrega", amanhã vem "Acho que é entrega". A API do Ollama aceita a opção de formato JSON, e você descreve os campos na instrução.

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "format": "json",
  "options": {"temperature": 0},
  "messages": [
    {"role": "system", "content": "Extraia da descrição do cliente de uma oficina mecânica um JSON com os campos: veiculo (texto), sintoma (texto), urgencia (baixa, media ou alta). Se faltar informação, use null. Responda só o JSON."},
    {"role": "user", "content": "Meu carro é um hatch 2019, está fazendo um barulho na roda da frente quando freio, preciso viajar sexta."}
  ],
  "stream": false
}'

Dois ajustes que fazem diferença. "format": "json" pede que a saída seja JSON válido. "temperature": 0, dentro de options, reduz a variação: a mesma entrada tende a dar a mesma saída, que é o que você quer numa integração. Mesmo assim, o sistema que recebe precisa validar: campo faltando, valor fora da lista, JSON quebrado. IA é entrada não confiável até prova em contrário.

Três integrações simples que resolvem problema real

1. Planilha que se classifica sozinha

Uma planilha com mensagens de clientes numa coluna. Um script curto lê cada linha, chama a API e escreve a categoria na coluna ao lado. Em Python, o coração é isto:

import requests

def classificar(mensagem):
    r = requests.post("http://localhost:11434/api/chat", json={
        "model": "llama3.2",
        "options": {"temperature": 0},
        "messages": [
            {"role": "system", "content": "Classifique em: orcamento, reclamacao, entrega, outro. Responda só com a categoria."},
            {"role": "user", "content": mensagem}
        ],
        "stream": False
    })
    return r.json()["message"]["content"].strip()

print(classificar("Comprei 20 sacos de cimento e não chegou"))

Ligar isso a uma planilha (ler as linhas, escrever a coluna) é meia dúzia de linhas a mais, e um assistente de nuvem escreve para você se você colar este trecho e descrever a planilha, sem os dados. Roda na mesma máquina do Ollama, então usa localhost.

2. Resumo automático de atendimento

Ao encerrar um atendimento no sistema de suporte ou no CRM, o texto da conversa vai para a API com a instrução "resuma em três linhas: problema, o que foi feito, pendência". O resumo volta para o registro do cliente. Aqui vale a política da aula 11: o resumo é dado pessoal, fica no sistema, com a mesma retenção.

3. Fluxo de automação sem código

Ferramentas de automação como o n8n, que pode ser instalado na sua própria máquina, têm um bloco de "requisição HTTP". Você monta o fluxo: formulário chega, bloco HTTP chama a API do Ollama com a instrução, a resposta vai para a planilha ou dispara um aviso. Sem escrever código. O curso de Automação sem Código deste site mostra o conceito de gatilho e ação em detalhe; aqui, a IA é só mais um bloco do fluxo, com a vantagem de não sair de casa.

O que vale para as três

• Rede: a integração roda na mesma máquina do Ollama ou, se em outra, só com o Ollama limitado por endereço no firewall (aula 10). Nunca pela internet.
• Revisão humana: nada com dado de cliente sai para o cliente sem gente olhar, ou sem uma regra explícita de quais casos podem ir direto, com registro.
• Registro: cada chamada, com data, entrada e saída, guardado com a retenção da aula 11. É a trilha de auditoria da integração.
• Limite: tamanho máximo de entrada e número de chamadas por minuto, para um erro no sistema não derrubar a máquina.
• Teste com a bateria: antes de ligar, rode a bateria da aula 6 pela API, não só pela tela. A instrução dentro da chamada pode se comportar diferente da instrução da interface.