KEPLIN Docs

Usar a IA nos scripts

Pedir texto, JSON com uma forma certa e embeddings aos modelos de IA da app, enviar ficheiros, tratar os erros e saber o que cada fornecedor faz.

Os scripts da app chamam a IA pelo módulo ai do SDK. O script escolhe o modelo pelo nome do alias, e o pedido sai do servidor da plataforma com as credenciais do fornecedor. O script nunca vê as chaves.

from api_manager import ai


def main(input):
    r = ai.chat("Resume em três frases: " + input["args"]["texto"])
    return {"resumo": r["text"]}

Antes de começar

  • O tenant tem de ter um fornecedor de IA activo, com modelos autorizados. Ver Fornecedores de IA.
  • A app tem de ter um alias para cada uso que o script pede. Sem model=, o script usa o alias predefinido desse uso. Ver Modelos de IA da app.

O que cada fornecedor faz

Fornecedor Texto, JSON e ferramentas Embeddings Imagens Transcrição Voz Lotes
OpenAI Sim Sim Sim Sim Sim Sim
Anthropic Sim Não Não Não Não Sim
Microsoft Foundry Sim Sim Sim Sim Sim Não
Amazon Bedrock Sim Titan e Cohere Nova Canvas, Titan e Stability Não Não Não
Google Cloud Sim Sim Sim Sim Sim Só pela Gemini API
OpenRouter Sim Sim Sim Não Não Não
Compatível com OpenAI Sim Conforme o servidor Conforme o servidor Conforme o servidor Conforme o servidor Não

Num fornecedor que não faz uma operação, a chamada dá o erro not_supported. Em qualquer fornecedor, a operação só funciona com um modelo que a faça: um modelo de texto não gera imagens.

As ferramentas e os lotes estão em Ferramentas e lotes, e as imagens, a transcrição e a voz em Imagens e áudio.

Pedir texto

ai.chat envia um pedido e devolve a resposta do modelo:

from api_manager import ai, log


def main(input):
    r = ai.chat(
        "Classifica este pedido de suporte: " + input["args"]["pedido"],
        system="És um assistente de apoio ao cliente. Respondes numa palavra: urgente, normal ou baixo.",
        model="texto",
        max_tokens=10,
        temperature=0,
    )
    log("classificação:", r["text"], r["usage"])
    return {"prioridade": r["text"].strip().lower()}
Parâmetro O que faz
prompt A pergunta.
system A instrução de sistema: o papel e as regras do modelo.
messages Uma conversa, em vez de prompt (ver Uma conversa).
model O nome do alias. Sem ele, vale o alias de texto predefinido.
max_tokens O tamanho máximo da resposta. Sem ele, vale o do alias e, depois, o da plataforma.
temperature De 0 a 2. Um valor baixo dá respostas mais previsíveis. Sem ele, vale o do modelo.
files Ficheiros que vão com a pergunta (ver Enviar ficheiros).
stream Um nome, para o texto aparecer no ecrã de quem chamou enquanto o modelo o escreve (ver Respostas em directo no ecrã).

O resultado é um dict:

Chave O que tem
text O texto da resposta.
stop_reason Porque parou o modelo: end, max_tokens, tool_use, refusal ou other.
usage Os tokens gastos, em input_tokens e output_tokens.
model, provider, alias Quem respondeu.

Um stop_reason igual a max_tokens quer dizer que a resposta foi cortada. Sobe o max_tokens ou pede uma resposta mais curta.

Uma conversa

Para continuar uma conversa, passa o histórico em messages, com os papéis user e assistant alternados:

from api_manager import ai


def main(input):
    r = ai.chat(
        messages=[
            {"role": "user", "content": "O meu nome é Ana."},
            {"role": "assistant", "content": "Olá, Ana!"},
            {"role": "user", "content": "Como me chamo?"},
        ],
    )
    return {"resposta": r["text"]}

Com messages e prompt ao mesmo tempo, o prompt entra como a última mensagem do utilizador. A lista também pode ir como primeiro argumento, sem messages=: ai.chat([...]).

Pedir JSON com uma forma certa

ai.json pede a resposta em JSON, valida-a contra um JSON Schema e devolve o JSON já lido:

from api_manager import ai

ESQUEMA = {
    "type": "object",
    "properties": {
        "nif": {"type": "string", "description": "NIF do cliente, 9 algarismos"},
        "total": {"type": "number", "description": "Total com IVA, em euros"},
    },
    "required": ["nif", "total"],
}


def main(input):
    factura = ai.json(
        "Extrai o NIF do cliente e o total desta factura.",
        schema=ESQUEMA,
        files=[input["args"]["factura"]],
    )
    return factura  # {"nif": "...", "total": 123.45}
  • O schema descreve a forma: os tipos, os campos obrigatórios e uma description em cada campo. Quanto melhor a descrição, melhor a resposta.
  • Uma resposta que não cumpre o schema dá o erro invalid_output. O script nunca recebe dados com a forma errada.
  • Os fornecedores que suportam saída estruturada recebem o schema no pedido. Os outros recebem-no na instrução de sistema, e a resposta é validada na mesma.

Enviar ficheiros

files= leva ficheiros da app com o pedido, em ai.chat e em ai.json. Aceita os argumentos do tipo Upload tal como chegam em input["args"], ou o que files.store devolve:

from api_manager import ai, files


def main(input):
    # um argumento do tipo Upload de uma API
    foto = input["args"]["foto"]
    estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])

    # um ficheiro criado pelo próprio script
    vendas = files.store(b"produto;quantidade\nCadeira;12\nMesa;30\n", "vendas.csv", "text/csv")
    melhor = ai.chat("Que produto vendeu mais? Responde só com o nome.", files=[vendas])

    return {"estado": estado["text"], "mais_vendido": melhor["text"]}
Tipo Como segue
Imagens PNG, JPEG, GIF e WebP Como imagem, para modelos que vêem imagens.
PDF Como documento, para modelos que lêem PDF.
Texto (txt, csv, json, md, xml e yaml) Como texto, antes da pergunta.

Cada ficheiro pode ter até 20 MB, e um pedido até 40 MB. Um modelo só de texto recusa imagens e PDF com o erro invalid_request.

Embeddings

ai.embed transforma texto em vectores, para procurar por significado e não só por palavras iguais:

from api_manager import ai


def semelhanca(a, b):
    produto = sum(x * y for x, y in zip(a, b))
    normas = (sum(x * x for x in a) ** 0.5) * (sum(y * y for y in b) ** 0.5)
    return produto / normas


def main(input):
    pergunta = ai.embed(input["args"]["pergunta"])  # um vector
    artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
    vectores = ai.embed(artigos)  # um vector por texto
    melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
    return {"artigo": artigos[melhor]}

Um texto devolve um vector. Uma lista devolve uma lista de vectores, pela mesma ordem, até 2048 textos por chamada. Sem model=, vale o alias de embeddings predefinido.

Os aliases da app

ai.models() devolve os aliases da app, cada um com o nome, o uso, a marca de predefinido, o fornecedor e o modelo. Serve para um script escolher o modelo durante a execução ou explicar porque é que falta um alias.

Erros

Uma chamada que falha lança ai.Error. O atributo code é igual em todos os fornecedores, e a mensagem diz o que aconteceu:

from api_manager import ai, log


def main(input):
    try:
        r = ai.chat(input["args"]["pergunta"])
    except ai.Error as e:
        log("IA:", e.code, str(e))
        if e.code in ("rate_limited", "unavailable", "timeout", "connection"):
            return {"tentar_mais_tarde": True}
        raise
    return {"resposta": r["text"]}
Código O que quer dizer
not_configured Falta o alias, o fornecedor está desactivado ou o modelo deixou de estar autorizado.
rate_limited O fornecedor recusou por excesso de pedidos.
timeout O fornecedor não respondeu dentro do tempo máximo.
unavailable, connection O fornecedor está em baixo ou não foi possível ligar.
auth, permission A chave foi recusada ou não tem permissão.
invalid_request O pedido não é válido para este fornecedor ou modelo.
invalid_output O JSON da resposta não cumpre o schema.
refused O modelo recusou responder.
not_supported O fornecedor não faz esta operação, ou o ficheiro é de um tipo que não segue.
cancelled A execução acabou antes da resposta.
max_steps O ai.run chegou ao máximo de passos sem resposta final.
not_found, unknown O modelo ou o endereço não existe, ou aconteceu outro erro.

Tempo limite e registos

  • Uma resposta pode demorar dezenas de segundos. O Tempo limite do script tem de chegar para todas as chamadas: num script com várias, sobe-o.
  • Quando a execução acaba, por tempo limite ou por cancelamento, os pedidos ainda à espera são cancelados no fornecedor.
  • Cada chamada escreve uma linha nos logs da execução, com o alias, o modelo e a duração, por exemplo [ai] texto (local/qwen2.5:0.5b): 1840 ms.
  • A plataforma não guarda o texto dos pedidos nem das respostas, a não ser que a app ligue a depuração (ver Modelos de IA da app). O pedido segue para o fornecedor de IA da app, por isso não lhe envies dados pessoais sem necessidade.

Perguntas frequentes

Posso usar a IA a partir de um widget ou do browser? Não. A IA só existe nos scripts, que correm no servidor, e assim as chaves nunca chegam ao browser. Um ecrã que precisa de IA chama uma API que corre um script.

O script diz not_configured e o alias existe. Confirma que o alias é do uso certo (um alias de embeddings não serve para ai.chat), que o fornecedor está activo e que o modelo continua autorizado nele.

Posso usar a biblioteca da OpenAI ou da Anthropic directamente? Podes instalá-la pelo painel pip, mas a chave teria de ficar num segredo da app, e o script perdia os aliases e os códigos de erro comuns. O módulo ai existe para isso.