playfetch

JogarFetch

O PlayFetch torna a adição de recursos de modelo de linguagem grande ao seu aplicativo de forma rápida e fácil.

Fundo

Os LLMs mudaram a forma como as equipes de produto trabalham. Partes cada vez maiores de aplicativos estão sendo construídas com linguagem natural. Freqüentemente, há membros da equipe que não são de engenharia envolvidos neste processo - estrategistas de conteúdo que se preocupam com o tom e a entrega do texto gerado, especialistas de domínio que trazem conhecimento altamente especializado para o conteúdo gerado e designers e gerentes de produto que têm um profundo conhecimento de suas necessidades de produto. Com esses novos membros da equipe envolvidos na prototipagem, desenvolvimento e manutenção de partes críticas de aplicativos junto com a equipe de engenharia, há muitas novas interações.

Essas novas interações entre engenheiros e o restante da equipe precisam de novas ferramentas. Os engenheiros não querem que o texto simples seja distribuído em suas bases de código, com solicitações constantes de atualizações apenas para descobrir que a nova versão não é realmente melhor. Os colaboradores de prompts ou cadeias não querem ter que esperar que um engenheiro integre suas atualizações antes de descobrir que elas não funcionam conforme o esperado. O PlayFetch resolve esses e muitos outros problemas que observamos em empresas que trabalham dessa forma.

O que é o PlayFetch?

• Um playground intuitivo criado em torno da colaboração com comentários, anotações, rótulos e classificações.
• Um sistema de versionamento não destrutivo que qualquer membro da equipe pode usar de forma transparente.
• Um ambiente de teste com importação e exportação de dados, cadeias de medição e testes automatizados de chat bot.
• Uma plataforma LLM que se integra perfeitamente a ferramentas de controle de origem, gerenciamento de projetos e armazenamento de vetores.
• Uma solução de hospedagem independente de modelo com uma API simples e unificada que oferece suporte a chamadas simples, bate-papo e interrupções manuais.
• Uma solução de análise e monitoramento focada nas necessidades de recursos do LLM.

Implantando PlayFetch no Google Cloud

PlayFetch foi otimizado para rodar no Google Cloud Platform. Siga as instruções abaixo para colocar sua própria instância em funcionamento. Presumiremos que você tenha feito um fork do repositório oficial do PlayFetch em https://github.com/yello-xyz/playfetch (para que você possa configurar a integração contínua). Se você planeja fazer alterações no código, poderá executar essas instruções várias vezes para configurar instâncias separadas para desenvolvimento, preparação e produção.

Configurar um novo projeto

• Configure sua conta do Google Cloud Platform em https://cloud.google.com/.
• Acesse o Console do Cloud em https://console.cloud.google.com.
• Navegue até IAM e Admin → Gerenciar recursos e clique em CRIAR PROJETO .
• Escolha um nome exclusivo (não pode ser alterado posteriormente) e clique em CRIAR .
• Navegue até Faturamento e, em Gerenciamento de conta , certifique-se de que o faturamento esteja habilitado para o novo projeto.

Configurar APIs

• Navegue até APIs e serviços → APIs e serviços ativados .
• Certifique-se de que o projeto recém-criado esteja selecionado no seletor de projetos na parte superior.
• Clique em ATIVAR APIS E SERVIÇOS .
• Pesquise API Admin do App Engine e clique em ATIVAR .
• Pesquise API Cloud Build e clique em ATIVAR .
• Pesquise API Cloud Datastore e clique em ATIVAR .
• Pesquise API Cloud Scheduler e clique em ATIVAR .
• Pesquise Ambiente flexível do Google App Engine e clique em ATIVAR .
• Pesquise API de gerenciamento de identidade e acesso (IAM) e clique em ATIVAR .
• Procure API Vertex AI e clique em ATIVAR .

Configurar o aplicativo App Engine

• Navegue até App Engine → Painel e clique em CRIAR APLICATIVO .
• Escolha um local (não pode ser alterado posteriormente).
• Deixe a opção de conta de serviço aberta (usaremos o padrão) e clique em PRÓXIMO .
• Ignore o painel de implantação (clique em FAZER ISSO MAIS TARDE ).

Configurar o armazenamento de dados

• Navegue até Datastore .
• Se você não vir o armazenamento de dados (padrão) , aguarde um minuto e atualize.
• Selecione o armazenamento de dados (padrão) .
• Selecione Tempo de vida (TTL) na barra lateral e clique em CRIAR POLÍTICA .
• Defina Kind como _nextauth_token e a propriedade Timestamp como expires e clique em CREATE .
• Crie outra política com cache de tipo e propriedade expiresAt .

Configurar o bucket de armazenamento

• Navegue até Cloud Storage → Buckets e selecione bucket [nome do projeto] .appspot.com .
• Em PERMISSÕES , clique em CONCEDER ACESSO .
• Adicione o principal allUsers e atribua a função Storage Object Viewer .
• Clique em SALVAR e PERMITIR ACESSO PÚBLICO (este intervalo será usado para armazenar avatares).

Crie a conta de serviço de build

• Navegue até IAM e Admin → Contas de serviço e clique em CRIAR CONTA DE SERVIÇO .
• Escolha um nome exclusivo e clique em CRIAR E CONTINUAR .
• Selecione a função Usuário da conta de serviço .
• Clique em ADICIONAR OUTRA FUNÇÃO e selecione App Engine Deployer .
• Clique em ADICIONAR OUTRA FUNÇÃO e selecione Agente de serviço do ambiente flexível do App Engine .
• Clique em ADICIONAR OUTRA FUNÇÃO e selecione Administrador de serviço do App Engine .
• Clique em ADICIONAR OUTRA FUNÇÃO e selecione Conta de serviço do Cloud Build .
• Clique em ADICIONAR OUTRA FUNÇÃO e selecione Administrador de índice do Cloud Datastore .
• Clique em ADICIONAR OUTRA FUNÇÃO e selecione Cloud Scheduler Admin .
• Clique em CONTINUAR e CONCLUIR .

[opcional] Configurar domínio personalizado

• Navegue até App Engine → Configurações .
• Em DOMÍNIOS PERSONALIZADOS, clique em ADICIONAR UM DOMÍNIO PERSONALIZADO .
• Insira o domínio e os subdomínios personalizados que deseja usar (seguindo as instruções para verificar a propriedade).
• Clique em CONTINUAR e CONCLUIR .
• Adicione os registros mostrados à configuração DNS do seu provedor de domínio personalizado.

[opcional, mas recomendado] Configurar a autenticação de usuário do Google OAuth

• Navegue até APIs e serviços → tela de consentimento do OAuth .
• Escolha o tipo de usuário Interno ou Externo dependendo do seu caso de uso e clique em CRIAR .
• Preencha os campos obrigatórios, clique em SALVAR E CONTINUAR e, em seguida, clique em ADICIONAR OU REMOVER ESCOPOS .
• Verifique o escopo .../auth/userinfo.profile e .../auth/userinfo.email e clique em ATUALIZAR e SALVAR E CONTINUAR .
• Se você escolheu o tipo de usuário externo acima, poderá adicionar algumas contas de teste (antes de publicar o aplicativo em produção). Certifique-se de incluir o endereço de e-mail que deseja usar para seu primeiro usuário administrador. Observe que você ainda precisará conceder acesso a esses usuários no PlayFetch.
• Clique em SALVAR E CONTINUAR e VOLTAR AO PAINEL .
• Selecione Credenciais na barra lateral e clique em CRIAR CREDENCIAIS e ID do cliente OAuth .
• Selecione Aplicativo da Web como Tipo de aplicativo e escolha um nome.
• Em Origens JavaScript autorizadas , adicione https:// [nome do projeto] .appspot.com (e domínio personalizado, se você tiver um). Se você também quiser usar a autenticação do Google ao executar o aplicativo localmente, adicione http://localhost:3000 também.
• Em URIs de redirecionamento autorizados , adicione https:// [nome do projeto] .appspot.com/api/auth/callback/google (e um URL semelhante para qualquer domínio personalizado). Se você também quiser usar a autenticação do Google ao executar o aplicativo localmente, adicione http://localhost:3000/api/auth/callback/google também.
• Clique em CRIAR e copie o ID do cliente e o segredo do cliente gerados para usar na configuração do gatilho de compilação abaixo.

Configurar a compilação

• Navegue até Cloud Build → Triggers e clique em CONNECT REPOSITORY .
• Selecione GitHub de origem (aplicativo Cloud Build GitHub) e clique em CONTINUAR para autenticar a conta GitHub onde você bifurcou o repositório (em uma janela pop-up).
• Selecione o repositório bifurcado, marque a caixa abaixo e clique em CONECTAR .
• Clique em CRIAR UM GATILHO .
• Escolha um nome para sua construção.
• Em Configuração , selecione Arquivo de configuração do Cloud Build (yaml ou json) .
• Para uma configuração mínima, você precisará adicionar as seguintes variáveis ​​de substituição ao gatilho de compilação (na seção Avançado ) clicando em ADICIONAR VARIÁVEL :
  • _ENCRYPTION_KEY : sequência aleatória de 64 dígitos hexadecimais .
  • _NEXTAUTH_SECRET : string aleatória de pelo menos 32 caracteres.
  • _NEXTAUTH_URL : URL público para sua instância, seja um domínio personalizado, se você tiver um, ou https:// [nome do projeto] .appspot.com .
  • _GCLOUD_STORAGE_BUCKET : o nome do intervalo do Cloud Storage onde você permitiu acesso público, por exemplo, [nome do projeto] .appspot.com .
  • _NOREPLY_EMAIL_USER e _NOREPLY_EMAIL_PASSWORD : conta do Gmail a ser usada para e-mails transacionais enviados. Pode ser uma conta dedicada no seu Google Workspace (com senha normal) ou uma conta separada do Gmail (com senha de aplicativo). Veja as instruções abaixo se precisar usar outro provedor de e-mail.
• Se você configurou a autenticação do Google acima, também deverá adicionar as seguintes variáveis:
  • _GOOGLE_CLIENT_ID e _GOOGLE_CLIENT_SECRET : os valores que você copiou acima após gerar credenciais OAuth.
• Em Conta de serviço , selecione a conta de serviço que você criou acima.
• Clique em CRIAR .
• Clique em EXECUTAR ao lado do gatilho recém-criado e clique em EXECUTAR TRIGGER.
• Selecione Histórico na barra lateral e aguarde para verificar se sua compilação foi concluída com êxito (pode levar de 10 a 15 minutos).

Inicialize seu ambiente PlayFetch

• Escolha um endereço de e-mail que será usado como login para o usuário administrador inicial.
• Abra um navegador e navegue até https:// [nome do projeto] .appspot.com/api/admin/init?admin= [[email protected]] (certifique-se de especificar o endereço de e-mail correto na consulta).
• Este endpoint executará um script para inicializar o armazenamento de dados (o que pode levar um minuto), mas você só poderá executá-lo uma vez (a menos que recrie o armazenamento de dados).
• Assim que o script for concluído, copie os valores de _PLAYFETCH_API_KEY e _PLAYFETCH_ENDPOINT_URL que são mostrados na resposta.
• Navegue até Cloud Build → Triggers , clique no trigger que você criou, adicione as duas variáveis ​​de substituição adicionais da etapa acima e clique em SALVAR .
• Execute seu gatilho de build novamente com as variáveis ​​adicionadas. Esta compilação pode precisar gerar índices de armazenamento de dados ausentes, por isso é melhor aguardar até que ela seja concluída novamente.

Agora você deve conseguir navegar até https:// [nome do projeto] .appspot.com e fazer login com o endereço de e-mail especificado para seu primeiro usuário administrador. Você pode usar a autenticação do Google (se configurada) ou links de e-mail (desde que as variáveis ​​_NOREPLY_EMAIL estejam configuradas corretamente). Usuários adicionais podem ter acesso no painel do administrador.

Executando o PlayFetch localmente

Se quiser contribuir com o PlayFetch ou depurar problemas, você pode seguir as instruções abaixo para executá-lo em sua máquina local.

Instale o nó e o npm

A maneira mais fácil de instalar a versão mais recente do node e do npm é executar o instalador mais recente.

Clonar o repositório

Abra com GitHub Desktop e clone em um diretório local ou conecte-se ao GitHub com SSH e execute git clone [email protected]:yello-xyz/playfetch.git . Se você já bifurcou o repositório, poderá cloná-lo.

Configurar ambiente

Para executar o aplicativo localmente, você precisará adicionar algumas variáveis ​​ao seu arquivo .env.local local (este arquivo é ignorado pelo controle de origem para evitar vazamento de chaves). Esses valores podem ser os mesmos que você especificou no gatilho de compilação do Google Cloud para sua instância de desenvolvimento (supondo que você esteja executando uma instância separada para produção, pois não quer correr o risco de vazar essas chaves), exceto _NEXTAUTH_URL , onde deve especificar o valor http://localhost:3000.

Você pode acessar o armazenamento de dados no Google Cloud a partir de sua máquina local (novamente supondo que você esteja executando uma instância de desenvolvimento separada para não corromper ou vazar dados de produção acidentalmente) instalando a CLI do Google Cloud e inicializando-a conforme explicado aqui (você pode pular as outras etapas). Execute os seguintes comandos para fazer login com sua conta do Google:

• gcloud auth login
• gcloud init
• gcloud auth application-default login
• gcloud init

Construir e executar

Agora você deve conseguir executar os seguintes comandos:

• npm install
• npm run build
• npm run start

Alternativamente, durante o desenvolvimento, você pode simplesmente executar o seguinte comando para executar uma compilação de depuração com atualização rápida:

npm run dev

Para executar todos os testes uma vez:

npm run test

Para observar as alterações e executar novamente automaticamente os conjuntos de testes relevantes:

npm run watch

Recursos opcionais

Para estender a configuração mínima, você pode configurar as seguintes variáveis ​​de ambiente (no gatilho de compilação do GCP ou no arquivo .env.local local) para ativar alguns recursos adicionais.

Integrações

• _GITHUB_CLIENT_ID , _GITHUB_CLIENT_SECRET : pode ser usado para configurar a autenticação GitHub OAuth (semelhante ao Google). Requer a configuração de um aplicativo GitHub OAuth.
• _GITHUB_APP_CLIENT_ID , _GITHUB_APP_CLIENT_SECRET , _GITHUB_APP_ID , _GITHUB_APP_PRIVATE_KEY , _NEXT_PUBLIC_GITHUB_APP_INSTALL_LINK : pode ser usado para configurar a integração do controle de origem. Requer a configuração de um aplicativo GitHub.
• _LINEAR_APP_CLIENT_ID , _LINEAR_APP_CLIENT_SECRET , _LINEAR_APP_WEBHOOK_SECRET : pode ser usado para configurar a integração de gerenciamento de tarefas. Também requer a configuração de um aplicativo Linear.
• _NOTION_TOKEN, _NOTION_ONBOARDING_PAGE_ID, _NOTION_WAITLIST_PAGE_ID : pode ser usado para sincronizar automaticamente inscrições na lista de espera e respostas de pesquisas de integração ao Notion. Requer a configuração de um aplicativo Notion.

Análise

• _GOOGLE_ANALYTICS_API_SECRET , _GOOGLE_ANALYTICS_MEASUREMENT_ID : pode ser usado para configurar análises do lado do servidor (GA4).
• _NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID , _NEXT_PUBLIC_COOKIE_DOMAIN , _NEXT_PUBLIC_COOKIE_NAME : pode ser usado para configurar cookies e análises do lado do cliente (Google Tag Manager).

Ambiente

• _GOOGLE_ANALYTICS_DASHBOARD_URL , _GOOGLE_ANALYTICS_REPORTS_URL , _GOOGLE_SEARCH_CONSOLE_URL , _INTEGRATION_TEST_URL , _SERVER_LOGS_URL : pode ser usado para adicionar vários links de diagnóstico no painel do administrador.
• _NEXT_PUBLIC_DOCS_URL , _NEXT_PUBLIC_SUPPORT_EMAIL : pode ser usado para gerar os links para Documentação e Suporte na área de trabalho e nas barras laterais do projeto.
• _NOREPLY_EMAIL_HOST , _NOREPLY_EMAIL_PORT : pode ser usado para configurar um provedor de e-mail alternativo para e-mails transacionais de saída.
• _API_URL : pode ser usado para dividir o tráfego entre o site e a API, por exemplo, se você tiver subdomínios separados apontando para sua instância.

Licença

PlayFetch é de código aberto sob uma licença permissiva do MIT.

Observe que o PlayFetch usa CodeMirror como dependência. Se você estiver usando o CodeMirror comercialmente, há uma expectativa social (mas não legal) de que você ajude a financiar sua manutenção.

Contribuindo

PlayFetch está sendo desenvolvido no GitHub. Contribuições são bem-vindas. Sinta-se à vontade para abrir problemas ou solicitações pull ao corrigir bugs ou adicionar recursos. Para começar, alguma inspiração pode ser encontrada em TODO.md.