A maioria das equipes não precisa de uma grande implantação de gateway de IA no primeiro dia. Elas precisam de um caminho curto de “temos uma conta” até “comparamos alguns modelos em trabalho real e sabemos o que testar a seguir”.
Este starter de integração do Flatkey foi criado para essa primeira sessão. Ele conecta as peças essenciais — acesso à API, uma primeira requisição, ferramentas de desktop, assistentes de programação, comparação de modelos, preços e repasse para a equipe — sem forçar você a adotar todos os fluxos de trabalho de uma vez.
A ideia operacional é simples: comece com uma chave de API do Flatkey e uma URL base compatível com OpenAI, depois escolha a superfície de trabalho que corresponda à pessoa que está fazendo a avaliação.
https://router.flatkey.ai/v1
Desenvolvedores podem usar um SDK ou o terminal. Os responsáveis por prompts podem começar no Cherry Studio. Equipes de programação podem adicionar um perfil do Flatkey no CC Switch. Todos podem trabalhar a partir da mesma lista restrita de modelos e comparar resultados antes de a equipe assumir um caminho de produção.
Visão geral da stack inicial do Flatkey
Use esta tabela para escolher a configuração mínima útil para seu primeiro teste.
| Seu objetivo imediato | Comece aqui | Como é o sucesso |
|---|---|---|
| Confirmar que a API funciona | Guia rápido do Flatkey | Uma resposta válida aparece no seu aplicativo e nos registros de uso |
| Comparar prompts manualmente | Guia de configuração do Cherry Studio | O mesmo prompt pode ser testado em uma pequena lista de modelos |
| Adicionar o Flatkey a um fluxo de programação | Guia de configuração do CC Switch | Um perfil local do Flatkey pode ser selecionado sem substituir todos os perfis existentes |
| Construir uma avaliação comparativa repetível | Fluxo de trabalho de teste de prompts com vários modelos | Cada modelo recebe os mesmos casos de teste e a mesma rubrica de pontuação |
| Escolher um candidato para produção | Checklist de avaliação de modelos de IA | Qualidade, latência, confiabilidade e custo efetivo são analisados em conjunto |
| Estimar o ajuste operacional | Preços do Flatkey | Sua lista restrita reflete o acesso atual aos modelos e a carga de trabalho esperada |
Você não precisa concluir todas as linhas. Um avaliador solo pode usar o guia rápido e o Cherry Studio. Uma equipe de engenharia pode ir diretamente do guia rápido para um harness de testes com SDK. Uma equipe de programação pode começar com o CC Switch e adicionar avaliação estruturada depois de identificar modelos promissores.
Etapa 1: escolha uma tarefa real, não uma demonstração genérica
A sessão de onboarding mais rápida começa com um trabalho representativo. Evite começar com um prompt vago, como “escreva algo criativo”. É difícil de pontuar e raramente se parece com o trabalho que justificará a integração.
Escolha uma tarefa com uma condição de aprovação visível, por exemplo:
- Extrair cinco campos obrigatórios de uma mensagem de suporte.
- Retornar JSON válido que corresponda ao esquema do seu aplicativo.
- Redigir uma resposta que siga uma política e um tom específicos.
- Explicar uma alteração de código sem inventar arquivos ou funções.
- Chamar uma ferramenta aprovada com os argumentos corretos.
Prepare cinco a dez exemplos antes de comparar modelos. Inclua casos comuns, um caso difícil e pelo menos um caso que deva falhar com segurança. Esse pequeno conjunto é suficiente para revelar diferenças óbvias sem transformar a primeira sessão em um programa completo de avaliação.
Mantenha estáveis o prompt, a forma esperada da saída e as regras de pontuação. O modelo deve ser a principal variável.
Step 2: Make one API call through the quickstart
Siga o Flatkey quickstart para criar uma chave de API, apontar um cliente compatível com OpenAI para o roteador Flatkey e fazer a primeira solicitação.
Seu checklist da primeira chamada é intencionalmente curto:
- Armazene a chave em uma variável de ambiente, em vez de no código-fonte.
- Defina a base URL como
https://router.flatkey.ai/v1. - Escolha um modelo atualmente disponível no catálogo ou console ao vivo do Flatkey.
- Envie um prompt representativo.
- Confirme que a resposta é analisável e que a solicitação aparece nos logs de uso.
Não adicione roteamento de fallback, retries complexos ou várias ferramentas antes de esta solicitação funcionar. Essas camadas podem ocultar se a chave, a base URL, a seleção de modelo e o contrato da solicitação estão corretos.
Assim que uma chamada for bem-sucedida, salve o prompt exato, o identificador do modelo, o horário da solicitação, a resposta, a latência e o uso. Esse registro se torna a linha de base para o próximo modelo.
Step 3: Choose the right evaluation surface
A melhor integração inicial depende de quem está fazendo o trabalho.
Cherry Studio for hands-on prompt comparison
Cherry Studio é útil quando um gerente de produto, designer de prompts, profissional de marketing, pesquisador ou avaliador técnico quer um espaço de trabalho gráfico para testar conversas e o comportamento do modelo.
Use o Cherry Studio API setup guide para adicionar o endpoint e a credencial do Flatkey. Em seguida, crie uma pequena rotina de comparação:
- Cole as mesmas instruções de sistema e a mesma entrada do usuário.
- Altere apenas o modelo, a menos que um modelo exija um ajuste de parâmetro documentado.
- Registre se a პასუხ passa nos requisitos rígidos.
- Pontue clareza, utilidade e preferência separadamente.
- Salve falhas assim como respostas fortes.
Esta é a maneira mais rápida de tornar as diferenças entre modelos visíveis para não desenvolvedores. Não substitui testes automatizados, mas pode produzir uma shortlist focada antes que a engenharia crie um harness.
CC Switch for coding-assistant profiles
CC Switch é um ponto de partida prático quando o caso de uso imediato é a configuração local de um assistente de programação. Siga o CC Switch setup guide para criar um perfil baseado em Flatkey e preservar a capacidade de alternar entre configurações aprovadas.
Avalie modelos de programação com tarefas específicas do repositório, em vez de um desafio genérico de programação. Peça a cada candidato para explicar um módulo real, propor um patch focado, identificar um teste com falha ou gerar um plano de migração. Revise se ele respeita os limites dos arquivos, segue instruções e evita afirmações não suportadas sobre a base de código.
Mantenha seu perfil existente disponível até que a nova rota tenha passado pelas tarefas que importam para sua equipe. Uma conexão bem-sucedida comprova acesso; não comprova que todo modelo seja apropriado para todo repositório ou nível de automação.
An SDK harness for repeatable results
Use um SDK ou script quando precisar de reprodutibilidade. Um cliente compatível com OpenAI pode enviar o mesmo conjunto de testes para vários IDs de modelos enquanto o seu avaliador armazena as respostas em um formato consistente.
O fluxo de trabalho de testes de prompts com vários modelos mostra como congelar o contrato da requisição, separar requisitos obrigatórios de preferências, registrar latência e uso e evitar alterar várias variáveis ao mesmo tempo.
Comece com dois ou três modelos. Mais candidatos geram mais trabalho de revisão e muitas vezes atrasam a decisão sem melhorá-la.
Etapa 4: Avalie o resultado que chega à produção
A requisição mais barata nem sempre é o resultado de menor custo. Uma resposta que exige correção manual, viola um schema, expira por tempo limite ou dispara novas tentativas repetidas pode custar mais do que um modelo mais caro que funciona na primeira tentativa.
Use quatro grupos de pontuação:
| Grupo de pontuação | Perguntas a responder |
|---|---|
| Sucesso da tarefa | A saída atendeu a todos os requisitos obrigatórios? |
| Qualidade | Foi precisa, útil, concisa e apropriada para o público? |
| Operações | A latência foi aceitável e a requisição foi concluída de forma confiável? |
| Economia | Qual é o custo efetivo por resultado aceito, incluindo novas tentativas e revisão? |
A lista de verificação de avaliação de modelos de IA oferece um fluxo de trabalho mais aprofundado para pontuação ponderada, verificações de saída estruturada, testes de limite de taxa, implantação canário e critérios de reversão.
Antes de escolher os finalistas, revise a atual página de preços da Flatkey. O acesso ao modelo e a economia podem mudar, então use a página ao vivo em vez de copiar números antigos para uma planilha de avaliação. Estime os tokens do prompt, os tokens de conclusão, o volume de requisições, as novas tentativas esperadas e qualquer tráfego de fallback para a carga de trabalho que você realmente planeja executar.
Etapa 5: Transforme um teste pessoal em um caminho pronto para a equipe
Uma integração pessoal funcionando é o começo da adoção, não o fim. Antes que o fluxo de trabalho se torne uma infraestrutura compartilhada, atribua responsáveis e adicione controles básicos.
Use esta lista de verificação de transição:
- Responsável pelo acesso: Controla a criação, o armazenamento, a rotação e a revogação da chave de API.
- Responsável pelo modelo: Mantém a lista curta de modelos aprovados e a política de roteamento em nível de tarefa.
- Responsável pela qualidade: Curadoria dos casos de teste, regras de pontuação e limites de regressão.
- Responsável pelas operações: Revisa uso, erros, latência, cotas e comportamento de fallback.
- Responsável pelo orçamento: Compara o uso previsto com os gastos reais e investiga desvios.
Se várias equipes ou regiões forem compartilhar o gateway, continue com o guia de gateway de IA para equipes. Se finanças ou operações precisarem de um processo de revisão reproduzível, use o guia de gestão de gastos com API de IA para conectar visibilidade de uso, cotas, registros de recarga e planejamento mensal.
O objetivo não é criar um comitê para um teste inicial. É garantir que o caminho do experimento até a produção tenha responsáveis nomeados antes que a integração se torne difícil de desfazer.
Um plano de início de integração do Flatkey em 30 minutos
Aqui está um cronograma prático para a primeira sessão:
| Tempo | Ação | Resultado |
|---|---|---|
| 0–5 minutos | Escolha uma tarefa real e cinco exemplos | Um pequeno conjunto de teste representativo |
| 5–10 minutos | Crie uma chave e conclua o quickstart | Uma solicitação de API registrada |
| 10–15 minutos | Conecte o Cherry Studio, o CC Switch ou um SDK | Uma superfície de avaliação pronta |
| 15–25 minutos | Execute dois ou três modelos nos mesmos exemplos | Respostas e medições comparáveis |
| 25–30 minutos | Revise os preços e escolha o próximo teste | Uma lista curta, um responsável e uma ação de acompanhamento |
No final da sessão, você deve conseguir responder a quatro perguntas:
- O caminho do Flatkey funciona em nossa ferramenta ou fluxo de código preferido?
- Quais candidatos de modelo atendem aos requisitos inegociáveis?
- Que evidências ainda faltam antes do uso em produção?
- Quem é o responsável pela próxima etapa de avaliação?
Isso já é progresso suficiente para o primeiro dia. Você pode adicionar conjuntos de dados maiores, juízes automatizados, roteamento de fallback e controles de equipe depois que a pilha inicial produzir uma lista curta confiável.
Comece com o caminho mais simples que possa ensinar algo
O Flatkey oferece suporte a várias superfícies de adoção, mas o caminho mais curto costuma ser o melhor: uma chave, uma URL base, uma tarefa representativa e uma superfície de avaliação.
Comece com o quickstart. Adicione o Cherry Studio para testes visuais de prompts, o CC Switch para perfis de assistente de programação, ou um harness de SDK para benchmarks repetíveis. Em seguida, use os preços atuais e critérios de avaliação focados em produção para decidir o que merece uma implementação maior.
O resultado é uma pilha inicial rápida o suficiente para um novo avaliador e estruturada o bastante para ser repassada à engenharia, operações e finanças quando o teste se tornar trabalho real.
