kayetana: IA nas suas próprias instalações

1Contexto

Muitas equipas querem usar IA no trabalho diário: responder a perguntas sobre políticas internas, classificar tickets de suporte, transcrever reuniões, redigir textos. O caminho óbvio são os serviços de IA na nuvem. Mas isso significa que o seu conteúdo acaba em servidores de terceiros, muitas vezes fora do seu controlo. Para contratos, processos de RH, dados de clientes ou planos de produto, muitas empresas simplesmente não podem aceitar isso.

Até agora, a alternativa exigia muito esforço. Executar modelos por conta própria implicava hardware de servidor, conhecimentos de modelos e API, e uma interface à parte para a equipa. A isso somavam-se a gestão de utilizadores, o registo e as regras de retenção.

O kayetana reúne todas estas peças numa única máquina. Um Mac Studio com Apple silicon é silencioso, eficiente e cabe em qualquer escritório. Os modelos abertos funcionam diretamente nele. A interface, a API, as funções, as estatísticas de utilização e as definições de privacidade já vêm integradas. Decide que modelos funcionam, quem tem acesso e durante quanto tempo os dados são guardados.

Os custos também são previsíveis. O kayetana é oferecido como taxa fixa pela plataforma, sem faturação por token nem por utilizador. Uma equipa maior ou mais pedidos não alteram isso.

2Visão geral da arquitetura

Todos os componentes funcionam no mesmo Mac Studio. Não é necessário nenhum serviço externo para a operação diária. Só precisa de internet para descarregar modelos e atualizações.

Os componentes:

• Mac Studio: o servidor. Apple silicon com memória unificada partilhada pela CPU e pela GPU, o que permite manter modelos maiores inteiramente em memória.
• Ollama: executa os modelos de linguagem e de embedding (porta 11434).
• Serviço complementar: trata da transcrição, do tokenizador, da leitura de documentos e do fine-tuning (porta 11435).
• Aplicação web: a interface do navegador e a API REST em /v2. Gere utilizadores, chaves de API, conjuntos de dados, o registo de utilização e as definições numa base de dados SQLite, e só escuta em 127.0.0.1, porta 4321.
• Proxy HTTPS (Caddy): aceita ligações da rede nas portas 443 e 80, encripta-as com certificado próprio e reencaminha-as para a aplicação web.
• Cópia de segurança: uma tarefa diária às 3h15 copia a base de dados e os ficheiros e guarda cada cópia durante 14 dias.

3Quem comunica com quem

Um navegador ou aplicação na rede da sua empresa liga-se ao proxy por HTTPS. O proxy passa o pedido à aplicação web, que só está acessível localmente no Mac Studio. A aplicação web verifica o início de sessão ou a chave de API, chama o Ollama ou o serviço complementar no endereço local 127.0.0.1 e devolve a resposta. Só então escreve uma entrada no registo de utilização, sem qualquer conteúdo.

O Ollama e o serviço complementar não têm início de sessão próprio. Por isso, ambos só escutam no endereço local 127.0.0.1 e não são acessíveis a partir de outras máquinas. A partir da rede, só está aberto HTTPS na porta 443 (mais a 80 para o redirecionamento). Para manutenção, um administrador acede aos serviços através de um túnel SSH.

4Funcionalidades

O kayetana cobre as tarefas típicas para as quais as equipas usam IA hoje. Todas as funcionalidades estão disponíveis no playground do navegador e através da API.

• Chat: system prompt, temperatura, máximo de tokens, raciocínio ligado ou desligado com orçamento, modo JSON, imagens como entrada para modelos com visão, ferramentas e function calling. Os modelos podem ser guardados para toda a equipa. Para cada pedido, o playground mostra código pronto a usar em Python, TypeScript e curl.
• Respostas a partir de documentos (RAG): cole texto ou carregue PDF, Word (docx, doc), RTF, ODT e HTML. Cada frase da resposta tem um número em expoente, com uma lista de fontes por baixo. Através da API, as fontes chegam como citações, também em streaming. No nosso exemplo, a resposta com fontes chega em 1,5 s.
• Embed: converta texto em vetores nos formatos float, int8, uint8, binary e ubinary. O playground mostra os resultados num gráfico 2D.
• Rerank: ordene documentos por relevância face a uma pergunta.
• Classify: atribua uma ou mais etiquetas a textos, com exemplos no pedido ou um classificador treinado. Cada etiqueta inclui uma pontuação de confiança.
• Tokens: divida o texto em tokens e volte a juntá-lo.
• Áudio: converta gravações em texto, com marcas temporais e idioma selecionável. Os formatos suportados incluem MP3, M4A, WAV, AIFF e FLAC, até 100 MB por ficheiro.
• Modelos: veja os modelos instalados com tamanho, comprimento de contexto e capacidades, descarregue novos pelo nome a partir da biblioteca do Ollama, elimine os que já não precisa e defina um modelo predefinido para cada tarefa.
• Conjuntos de dados e embed jobs: carregue CSV, JSONL, TXT, PDF e Word. Os embed jobs geram embeddings de conjuntos de dados completos em segundo plano, com barra de progresso e o resultado como download JSONL.
• Fine-tuning: treine um modelo de chat com os seus próprios exemplos de conversa através de LoRA, ou crie um classificador a partir de dados etiquetados.
• Utilização: tokens e pedidos por dia, chave e modelo, além do tempo de resposta e da taxa de erros, em 7, 30, 90 ou 365 dias.
• Equipa: funções, convites por link e reposição de palavras-passe pelos administradores.

5Casos de utilização típicos

As funcionalidades do kayetana combinam-se em aplicações muito semelhantes de empresa para empresa. Os exemplos seguintes mostram que componentes trabalham em conjunto em cada caso.

• Perguntas sobre documentos internos: são carregados regulamentos, contratos e manuais. Os colaboradores fazem perguntas no browser e recebem respostas em que cada frase remete para a sua fonte. Componentes: respostas a partir de documentos, embed e rerank.
• Triagem de pedidos recebidos: os tickets de suporte e os e-mails são atribuídos automaticamente a categorias. Para começar, bastam alguns exemplos no pedido. Quando tiver dados etiquetados suficientes, pode transformá-los no seu próprio classificador. Componentes: classificar, datasets, fine-tuning.
• Reuniões e mensagens de voz: as gravações são convertidas em texto com marcas temporais. Depois, um modelo de chat pode resumir o texto ou extrair tarefas. Componentes: áudio e chat.
• Pesquisa em grandes coleções: coleções inteiras de documentos são carregadas como dataset e processadas com embeddings em segundo plano. Utiliza os vetores na sua própria aplicação de pesquisa. Componentes: datasets, embed jobs, rerank.
• As suas próprias aplicações: as ferramentas internas chamam o kayetana através da API. Cada aplicação tem a sua própria API key com um limite mensal, para manter o controlo da utilização. Componentes: REST API, API keys, utilização.

6Como surge uma resposta com fontes

Para muitas equipas, as respostas a partir de documentos são o caso de utilização mais importante, por isso aqui fica o processo em detalhe. Introduz uma pergunta e adiciona documentos, como texto ou como ficheiros. O serviço complementar converte primeiro os ficheiros em texto. Depois, a aplicação web passa a pergunta e os documentos ao modelo de chat selecionado, com a instrução de responder apenas com base nesses documentos.

O modelo escreve a resposta e associa cada frase à passagem de onde veio. Na interface vê números em expoente com a lista de fontes por baixo. Através da API recebe a mesma informação de forma estruturada como citações, mesmo enquanto a resposta ainda está a ser transmitida. Assim, cada afirmação verifica-se rapidamente.

Nem a pergunta, nem os documentos, nem a resposta são guardados em momento algum. O registo de utilização mostra apenas que um pedido de chat com um determinado modelo e um determinado número de tokens ocorreu a uma determinada hora.

7Fluxos de dados e proteção de dados

Todo o processamento acontece no Mac Studio. Uma pergunta de chat, um documento carregado ou uma gravação de voz são processados localmente. Nenhum conteúdo é enviado para serviços externos.

Os prompts e as respostas nunca são guardados. Isto aplica-se ao playground e à API. Quando um pedido termina, o kayetana regista apenas metadados: hora, endpoint, modelo, estado, número de tokens e duração. Vê como a plataforma é utilizada sem guardar qualquer conteúdo.

Fica guardado aquilo que cria deliberadamente: contas de utilizador, API keys, modelos da equipa, datasets, resultados de embed jobs e os seus próprios modelos e classificadores treinados. Os documentos que cola no playground para uma única pergunta são usados apenas nesse pedido.

Na página de privacidade define os prazos de conservação, separadamente para o registo de utilização e para os datasets: ilimitado, 7, 30, 90 ou 365 dias. A plataforma elimina automaticamente as entradas mais antigas. Também pode limpar manualmente o registo de utilização a qualquer momento.

8Notas para encarregados de proteção de dados

O kayetana ajuda-o a utilizar IA de forma respeitadora da privacidade: os dados ficam na empresa, o conteúdo não é guardado e a conservação e a eliminação são configuráveis. Se uma utilização concreta é permitida depende da sua finalidade, dos seus dados e dos seus processos. A plataforma não faz essa avaliação por si.

Tenha em conta que as cópias de segurança contêm os dados dos últimos 14 dias. O que for eliminado do registo de utilização ou de um dataset pode ainda estar numa cópia durante até 14 dias. O mesmo se aplica a qualquer cópia externa adicional, cuja conservação é definida por si.

9Segurança

Com o kayetana, a segurança começa pela localização: o servidor está na sua rede e é você quem decide quem lhe pode aceder. As medidas seguintes assentam nisso.

• Funções: Owner, Admin e Member. Os administradores convidam novos membros por link e emitem links de reposição de palavra-passe.
• Início de sessão: uma sessão é válida durante 14 dias. Após 10 tentativas falhadas, o início de sessão fica bloqueado durante 15 minutos.
• Single sign-on: os Owners ligam um fornecedor de identidade através de OpenID Connect (authorization code flow com PKCE, ID token verificado) ou SAML 2.0 (assertion assinada obrigatória, sem inícios de sessão iniciados pelo IdP, metadados SP em /sso/metadata). É obrigatório indicar os domínios de e-mail permitidos. No modo “Apenas SSO”, o início de sessão com palavra-passe fica disponível apenas para os Owners como acesso de emergência.
• API keys: as aplicações autenticam-se com um bearer token. Cada chave tem um limite mensal. Quando é atingido, a API responde com o estado 429.
• Rastreabilidade: o registo de utilização mostra os pedidos por chave e modelo, sem conteúdo.
• HTTPS: o Caddy cifra todas as ligações na rede com o seu próprio certificado. Para que os browsers o aceitem, o certificado raiz é marcado uma vez como fidedigno em cada computador.
• Rede: a aplicação web escuta apenas em 127.0.0.1. A partir da rede só o proxy HTTPS está acessível. O Ollama e o serviço complementar também escutam apenas localmente.
• Cópias de segurança: diariamente às 3h15, conservadas durante 14 dias. Como ficam no mesmo disco, recomendamos uma cópia externa adicional.
• Funcionamento offline: depois de descarregados os modelos, o kayetana não precisa de internet. Pode desligar totalmente o servidor da internet.

10Modelos e hardware

O kayetana inclui modelos abertos escolhidos para tarefas comuns. Todos têm licença aberta (Apache 2.0 ou MIT). Pode descarregar mais modelos abertos pelo nome a partir da biblioteca do Ollama sempre que precisar.

O gestor de modelos mostra o tamanho, o comprimento de contexto e as capacidades de cada modelo instalado, por exemplo se consegue processar imagens ou chamar ferramentas. Define um modelo predefinido para chat, embed e rerank. Através da API, /v2/models devolve os modelos disponíveis, opcionalmente filtrados por tarefa. Os seus próprios modelos com fine-tuning aparecem na mesma lista com o prefixo ft- ou clf-.

11Memória recomendada

Recomendamos um Mac Studio com 36 GB de memória ou mais. Isso permite executar modelos até cerca de 20 mil milhões de parâmetros em paralelo com a pesquisa e a transcrição. Com mais memória, pode executar modelos maiores.

Para um funcionamento fiável 24 horas por dia, o Mac Studio não deve entrar em repouso quando o ecrã se desliga e deve ter um endereço IP fixo no seu router.

12Operação

O kayetana foi concebido para exigir pouca manutenção. Todos os serviços correm numa conta de utilizador normal do Mac Studio, sem direitos de administrador.

• Instalação por script: um script de configuração instala o ambiente de execução, compila a aplicação e configura a app, o proxy HTTPS e a cópia de segurança como serviços. Um segundo script instala o Ollama e descarrega os modelos adequados à memória disponível.
• Atualizações: o mesmo script instala as atualizações. Compila a nova versão e reinicia os serviços. A base de dados e os ficheiros são mantidos.
• Cópia de segurança: todos os dias às 3h15, uma tarefa faz uma cópia consistente da base de dados, dos datasets e dos classificadores. As cópias com mais de 14 dias são eliminadas.
• Restauro: copie a base de dados e os ficheiros de uma cópia de segurança para o respetivo lugar e reinicie a app.
• Reinícios: após um reinício ou uma falha de energia, todos os serviços arrancam sozinhos. Se um serviço falhar, é reiniciado automaticamente.

13Integração por API

Todas as funcionalidades estão disponíveis através de uma REST API em /v2. As aplicações autenticam-se com uma API key no cabeçalho (Authorization: Bearer). As respostas chegam em JSON e o chat pode ser transmitido via server-sent events. O playground mostra o código correspondente a cada pedido.

14Comece em quatro passos

• 1. Chamada e demonstração: em 30 minutos mostramos-lhe a plataforma com os seus próprios exemplos e definimos as tarefas com que quer começar.
• 2. Hardware e configuração: disponibiliza um Mac Studio. O kayetana é configurado por script, os modelos são descarregados e o certificado raiz é instalado nos computadores da sua equipa.
• 3. Equipa e regras: convida a sua equipa, atribui funções, define prazos de conservação e cria API keys com limites mensais.
• 4. Primeiros casos de utilização: a sua equipa trabalha no playground, os modelos de texto são partilhados e as primeiras aplicações ligam-se através da API. As estatísticas de utilização mostram o que funciona.

15Limites e uma avaliação honesta

O kayetana foi pensado deliberadamente para uma única máquina nas suas próprias instalações. Isso implica limites que deve conhecer antes de decidir.

• Os modelos muito grandes precisam de mais memória do que um Mac Studio na configuração recomendada tem. Para esses, precisa de mais memória ou de um serviço de IA na cloud.
• O rerank funciona através da semelhança de embeddings com bge-m3. Não está incluído um modelo cross-encoder dedicado.
• De momento, o fine-tuning de modelos de chat está disponível para qwen3:4b-instruct.
• De momento, a interface de utilizador está em alemão.
• O Ollama e o serviço complementar não têm início de sessão próprio, pelo que só estão acessíveis localmente no Mac Studio; quem tiver acesso a essa máquina consegue chegar aos modelos. Proteja-a em conformidade (contas de utilizador, acesso físico).
• As cópias de segurança ficam no mesmo disco que os dados. Só uma cópia externa adicional o protege se o equipamento avariar.
• Como qualquer modelo de linguagem, os modelos do kayetana podem cometer erros. As citações facilitam a verificação, mas não a substituem.
• O kayetana não substitui aconselhamento jurídico. Ajuda-o na proteção de dados, mas não garante a conformidade com o RGPD.

16Contacto

O kayetana é desenvolvido pela neonotu GmbH. Preços sob consulta. É uma tarifa fixa pela plataforma, sem faturação por token nem por utilizador.

neonotu GmbH, Edelsbergstraße 8, 80686 Munique, Alemanha. Telefone +49 89 2000 7975 0. Ou contacte-nos através do formulário de contacto do nosso site.