O Gemma 3n foi lançado com entrada de áudio e otimizado para uso em dispositivos do dia a dia. Saiba mais

Crie um assistente de programação de IA pessoal com o Gemma

Receber assistência de código de modelos de inteligência artificial (IA) pode ser muito útil, mas e se você não puder usar modelos de IA generativa hospedados de terceiros devido a restrições de conectividade, custo ou segurança de dados? A família de modelos Gemma do Google está disponível para download e execução no seu próprio hardware. Assim, você pode manter tudo local e até mesmo ajustar o modelo para funcionar melhor com sua base de código.

Executar sua própria instância do Gemma ou do CodeGemma pode oferecer assistência de programação de IA com baixa latência, alta disponibilidade, custo potencialmente menor e a capacidade de manter todos os dados de programação na sua própria rede. Este projeto mostra como configurar seu próprio serviço da Web para hospedar o Gemma e conectá-lo a uma extensão do Microsoft Visual Studio Code, para facilitar o uso do modelo durante a programação. Esse projeto inclui dois subprojetos: um para configurar e encapsular a Gemma em um serviço da Web e um segundo projeto para uma extensão do VS Code que se conecta e usa o serviço da Web.

Para conferir uma visão geral em vídeo desse projeto e como estendê-lo, incluindo insights das pessoas que o criaram, assista o vídeo Assistente de código de IA pessoal do Build with Google AI. Você também pode analisar o código deste projeto no repositório de código do Gemma Cookbook. Caso contrário, comece a estender o projeto usando as instruções a seguir.

Visão geral

Neste tutorial, mostramos como configurar e estender dois projetos: um serviço da Web para o Gemma e uma extensão do VS Code para usar esse serviço. O serviço da Web usa Python, Keras, JAX e as bibliotecas FastAPI para disponibilizar o modelo Gemma e processar solicitações. A extensão do VS Code, chamada Pipet, adiciona comandos à paleta de comandos que permitem fazer solicitações ao serviço da Web Gemma selecionando código, texto ou comentários em uma janela de edição de código, conforme mostrado na Figura 1.

Captura de tela da interface do usuário da extensão do VS Code

Figura 1. Interface do usuário de comando do projeto para a extensão Pipet no Visual Studio Code

O código-fonte completo dos dois projetos está disponível no repositório de código do Cookbook da Gemma. Você pode estender os dois projetos para adaptá-los às suas necessidades e ao fluxo de trabalho preferido.

Configurar o projeto

Estas instruções mostram como preparar o projeto para desenvolvimento e testes. As etapas gerais de configuração incluem a instalação do software de pré-requisito, a clonagem do projeto do repositório de código, a definição de algumas variáveis de ambiente, a instalação de bibliotecas Python e Node.js e o teste do aplicativo da Web.

Instalar o software necessário

Este projeto usa Python 3, ambientes virtuais (venv), Node.js e Node Package Manager (npm) para gerenciar pacotes e executar os dois projetos.

Para instalar o software necessário:

Instale o Python 3, o pacote de ambiente virtual (venv) para Python, o Node.js e o gerenciador de pacotes do Node.js (npm):
```
sudo apt update
sudo apt install git pip python3-venv nodejs npm
```

Clonar o projeto

Faça o download do código do projeto para o computador de desenvolvimento. Você precisa do software de controle de origem git para recuperar o código-fonte do projeto.

Para fazer o download do código do projeto:

Clone o repositório git usando o comando a seguir:

git clone https://github.com/google-gemini/gemma-cookbook.git

Opcional: configure seu repositório git local para usar o checkout esparso, assim você terá apenas os arquivos do projeto:
```
cd gemma-cookbook/
git sparse-checkout set Demos/personal-code-assistant/
git sparse-checkout init --cone
```

Projeto de serviço da Web do Gemma

A parte do serviço da Web deste projeto (gemma-web-service) cria uma instância hospedada de forma independente do Gemma 2 2B envolvida em um serviço da Web básico para processar solicitações e respostas de geração. A extensão do VS Code, abordada mais adiante neste tutorial, se conecta a esse serviço para processar solicitações de assistência de código.

Estas instruções mostram como preparar o projeto para desenvolvimento e testes. As etapas gerais de configuração incluem a instalação de software pré-requisito, a clonagem do projeto do repositório de código, a definição de algumas variáveis de ambiente, a instalação de bibliotecas Python e o teste do serviço da Web.

Requisitos de hardware

Execute o projeto de serviço da Web Gemma em um computador com uma unidade de processamento gráfico (GPU) ou uma unidade de processamento de tensor (TPU) e memória suficiente para armazenar o modelo. Para executar a configuração do Gemma 2 2B neste projeto de serviço da Web, você precisa de cerca de 16 GB de memória de GPU, aproximadamente a mesma quantidade de RAM normal e um mínimo de 20 GB de espaço em disco.

Se você estiver implantando o projeto de serviço da Web Gemma em uma instância de VM do Google Cloud, configure a instância seguindo estes requisitos:

Hardware de GPU: uma NVIDIA T4 é necessária para executar este projeto (recomenda-se NVIDIA L4 ou superior).
Sistema operacional: escolha uma opção de Aprendizado profundo no Linux, especificamente VM de aprendizado profundo com CUDA 12.3 M124 com drivers de software de GPU pré-instalados.
Tamanho do disco de inicialização: provisione pelo menos 20 GB de espaço em disco para seus dados, modelo e software de suporte.

Configurar projeto

Este projeto usa o Python 3 e ambientes virtuais (venv) para gerenciar pacotes e executar o serviço da Web. Instale as bibliotecas Python com o ambiente virtual venv Python ativado para gerenciar pacotes e dependências do Python. Ative o ambiente virtual Python antes de instalar as bibliotecas Python com o script setup_python ou com o instalador pip. Para mais informações sobre como usar ambientes virtuais do Python, consulte a documentação do venv do Python.

Para instalar as bibliotecas Python:

Em uma janela de terminal, navegue até o diretório gemma-web-service:
```
cd Demos/personal-code-assistant/gemma-web-service/
```
Configure e ative um ambiente virtual Python (venv) para este projeto:
```
python3 -m venv venv
source venv/bin/activate
```
Instale as bibliotecas necessárias do Python para este projeto usando o script setup_python:
```
./setup_python.sh
```

Defina as variáveis de ambiente

Esse projeto exige algumas variáveis de ambiente para ser executado, incluindo um nome de usuário e um token da API do Kaggle. Você precisa ter uma conta do Kaggle e solicitar acesso aos modelos Gemma para fazer o download deles. Para este projeto, adicione seu nome de usuário e token da API do Kaggle em um arquivo .env, que é usado pelo programa de serviço da Web para baixar o modelo.

Para definir as variáveis de ambiente:

Siga as instruções na documentação do Kaggle para conseguir seu nome de usuário e token da API.
Siga as instruções em Acessar o Gemma na página Configuração do Gemma para ter acesso ao modelo.
Crie um arquivo de variável de ambiente para o projeto. Para isso, crie um arquivo de texto .env neste local no clone do projeto:
```
personal-code-assistant/gemma-web-service/.env
```
Depois de criar o arquivo de texto .env, adicione as seguintes configurações a ele:
```
KAGGLE_USERNAME=<YOUR_KAGGLE_USERNAME_HERE>
KAGGLE_KEY=<YOUR_KAGGLE_KEY_HERE>
```

Executar e testar o serviço da Web

Depois de concluir a instalação e a configuração do projeto, execute o aplicativo da Web para confirmar se você o configurou corretamente. Faça isso como uma verificação de linha de base antes de editar o projeto para seu próprio uso.

Para executar e testar o projeto:

Em uma janela de terminal, navegue até o diretório gemma-web-service:
```
cd personal-code-assistant/gemma-web-service/
```
Execute o aplicativo usando o script run_service:
```
./run_service.sh
```
Depois de iniciar o serviço da Web, o código do programa lista um URL em que é possível acessar o serviço. Normalmente, esse endereço é:
```
http://localhost:8000/
```
Teste o serviço executando o script test_post:
```
./test/test_post.sh
```

Quando você executar e testar o serviço com esse script, estará pronto para se conectar a ele com a extensão do VS Code na próxima seção deste tutorial.

Projeto de extensão do VS Code

A extensão do VS Code deste projeto (pipet-code-agent-2) cria uma extensão de software do aplicativo Microsoft Visual Studio Code projetada para adicionar novos comandos de programação de IA. Essa extensão se comunica com o serviço da Web do Gemma descrito anteriormente neste tutorial. A extensão se comunica com os serviços da Web por HTTP usando mensagens no formato JSON.

Configurar projeto

Estas instruções mostram como configurar o projeto do Pipet Code Agent v2 para desenvolvimento e testes. As etapas gerais são: instalar o software necessário, executar a instalação da configuração, definir uma configuração de extensão e testar a extensão.

Instalar o software necessário

O projeto Pipet Code Agent é executado como uma extensão do Visual Studio Code da Microsoft e usa o Node.js e a ferramenta Node Package Manager (npm) para gerenciar pacotes e executar o aplicativo.

Para instalar o software necessário:

Faça o download e instale o Visual Studio Code para sua plataforma.
Siga as instruções de instalação para sua plataforma e verifique se o Node.js está instalado.

Configurar bibliotecas do projeto

Use a ferramenta de linha de comando npm para baixar as dependências necessárias e configurar o projeto.

Para configurar o código do projeto:

Navegue até o diretório raiz do projeto do Pipet Code Agent.
```
cd Demos/personal-code-assistant/pipet-code-agent-2/
```
Execute o comando de instalação para baixar as dependências e configurar o projeto:
```
npm install
```

Configurar a extensão

Agora você pode testar a instalação executando o Pipet Code Agent como uma extensão de desenvolvimento no VS Code no seu dispositivo. O teste abre uma janela separada do VS Code Extension Development Host, onde a nova extensão está disponível. Nessa nova janela, configure as definições que a extensão usa para acessar seu serviço da Web pessoal da Gemma.

Agente de código do Pipet em execução na janela do host de desenvolvimento de extensão Figura 2. Janela do host de desenvolvimento de extensão do VS Code com as configurações da extensão Pipet.

Para configurar e testar sua configuração:

Inicie o aplicativo VS Code.
No VS Code, crie uma janela selecionando Arquivo > Nova janela.
Abra o projeto do Pipet Code Agent selecionando Arquivo > Abrir pasta e escolhendo a pasta personal-code-assistant/pipet-code-agent-2/.
Abra o arquivo pipet-code-agent-2/src/extension.ts.
Execute a extensão no modo de depuração selecionando Executar > Iniciar depuração e, se necessário, selecione a opção Host de desenvolvimento de extensão do VS Code. Esta etapa abre uma janela separada do Extension Development Host.
Na nova janela do VS Code, abra as configurações do VS Code selecionando Code > Settings > Settings.
Defina o endereço do host do servidor de serviço da Web da Gemma como uma configuração. No campo Configurações de pesquisa, digite Gemma, selecione a guia Usuário e, na configuração Gemma > Serviço: host, clique no link Editar em settings.json e adicione o endereço do host, como 127.0.0.1, localhost ou my-server.my-local-domain.com:
```
"gemma.service.host": "your-host-address-here"
```
Salve as mudanças no arquivo settings.json e feche as guias de configurações.

Testar a extensão

Para testar os comandos de extensão:

Na janela Extension Development Host do VS Code, selecione qualquer código na janela do editor.
Abra a paleta de comandos selecionando Visualizar > Paleta de comandos.
Na paleta de comandos, digite Pipet e selecione um dos comandos com esse prefixo.

Modificar comandos atuais

Modificar os comandos fornecidos no Pipet Code Agent é a maneira mais simples de mudar o comportamento e os recursos da extensão. Essas informações de contexto do comando orientam o modelo generativo do Gemma na criação de uma resposta. Ao mudar as instruções do comando Pipet, você altera o comportamento de cada um deles.

Este conjunto de instruções explica como modificar o comando review.ts mudando o texto do comando.

Para se preparar para editar o comando review.ts:

Inicie o aplicativo VS Code.
No VS Code, crie uma janela selecionando Arquivo > Nova janela.
Abra o projeto do Pipet Code Agent selecionando Arquivo > Abrir pasta e escolhendo a pasta pipet-code-agent/.
Abra pipet-code-agent/src/review.ts.

Para modificar o comportamento do comando review.ts:

No arquivo review.ts, mude a penúltima linha da constante PROMPT_INSTRUCTIONS para adicionar Also note potential performance improvements.

const PROMPT_INSTRUCTIONS = `
Reviewing code involves finding bugs and increasing code quality. Examples of
bugs are syntax errors or typos, out of memory errors, and boundary value
errors. Increasing code quality entails reducing complexity of code, eliminating
duplicate code, and ensuring other developers are able to understand the code.
Also note potential performance improvements.

Write a review of the following code:
`;

Salve as mudanças no arquivo review.ts.

Para testar o comando modificado:

Na janela do projeto da extensão Pipet do VS Code, abra o arquivo src/extension.ts.
Crie o código atualizado selecionando Terminal > Executar tarefa de build... e depois a opção npm: compile.
Para reiniciar o depurador, selecione Run > Restart Debugging.
Na janela Extension Development Host do VS Code, selecione qualquer código na janela do editor.
Abra a paleta de comandos selecionando Visualizar > Paleta de comandos.
Na paleta de comandos, digite Pipet e selecione o comando Pipet: Review the selected code.

Criar novos comandos

Você pode estender o Pipet criando novos comandos que realizam tarefas completamente novas com o modelo Gemma. Cada arquivo de comando, como comment.ts ou review.ts, é quase totalmente independente e inclui código para coletar texto do editor ativo, criar um comando, se conectar ao serviço da Web do Gemma, enviar um comando e processar a resposta.

Este conjunto de instruções explica como criar um novo comando usando o código de um comando existente, question.ts, como modelo.

Para criar um comando que recomenda nomes para funções:

Faça uma cópia do arquivo pipet-code-agent-2/src/question.ts chamado new-service.ts no diretório src/.
No VS Code, abra o arquivo src/new-service.ts.

Mude as instruções de comando no novo arquivo editando o valor PROMPT_INSTRUCTIONS.

// Provide instructions for the AI model
const PROMPT_INSTRUCTIONS = `
Build a Python web API service using FastAPI and uvicorn.
- Just output the code, DO NOT include any explanations.
- Do not include an 'if __name__ == "__main__":' statement.
- Do not include a '@app.get("/")' statement
- Do not include a '@app.get("/info")' statement
`;

Adicione o boilerplate do serviço criando uma nova constante BOILERPLATE_CODE.

const BOILERPLATE_CODE = `
# the following code for testing and diagnosis:
@app.get("/")
async def root():
    return "Server: OK"

@app.get("/info")
async def info():
    return "Service using FastAPI version: " + fastapi.__version__

# Run the service
if __name__ == "__main__":
    # host setting makes service available to other devices
    uvicorn.run(app, host="0.0.0.0", port=8000)
`;

Mude o nome da função de comando para newService() e atualize a mensagem de informações dela.

export async function newService() {
  vscode.window.showInformationMessage('Building new service from template...');
...

Atualize o código de montagem do comando para incluir o texto selecionado no editor e o PROMPT_INSTRUCTIONS.

// Build the full prompt using the template.
  const promptText = `${selectedCode}${PROMPT_INSTRUCTIONS}`;

Mude o código de inserção da resposta para incluir a resposta e o código padrão.

// Insert answer after selection.
editor.edit((editBuilder) => {
    editBuilder.insert(selection.end, "\n\n" + responseText);
    editBuilder.insert(selection.end, "\n" + BOILERPLATE_CODE);
});

Salve as mudanças no arquivo new-service.ts.

Integrar o novo comando

Depois de concluir o código do novo comando, é necessário integrá-lo ao restante da extensão. Atualize os arquivos extension.ts e package.json para tornar o novo comando parte da extensão e permitir que o VS Code invoque o novo comando.

Para integrar o comando new-service ao código da extensão:

No VS Code, abra o arquivo pipet-code-agent-2/src/extension.ts.
Adicione o novo arquivo de código à extensão com uma nova instrução de importação.
```
import { newService } from './new-service';
```

Registre o novo comando adicionando o seguinte código à função activate().

export function activate(context: vscode.ExtensionContext) {
    ...
    vscode.commands.registerCommand('pipet-code-agent.newService', newService);
}

Salve as mudanças no arquivo extension.ts.

Para integrar o comando name ao pacote de extensão:

No VS Code, abra o arquivo pipet-code-agent/package.json.

Adicione o novo comando à seção commands do arquivo de pacote.

"contributes": {
  "commands": [
    ...
    {
      "command": "pipet-code-agent.newService",
      "title": "Pipet: Generate a FastAPI service."
    }
  ],

Salve as mudanças no arquivo package.json.

Testar o novo comando

Depois de concluir a programação do comando e integrá-lo à extensão, é possível testá-lo. O novo comando só está disponível na janela Extension Development Host do VS Code, e não na janela do VS Code em que você editou o código da extensão.

Para testar o comando modificado:

Na janela do projeto da extensão Pipet do VS Code, abra o arquivo src/extension.ts.
Crie o código atualizado selecionando Terminal > Executar tarefa de build... e depois a opção npm: compile.
Na janela do projeto da extensão Pipet do VS Code, reinicie o depurador selecionando Executar > Reiniciar depuração, que reinicia uma janela separada do Host de desenvolvimento de extensão.
Na janela Extension Development Host do VS Code, selecione um código na janela do editor.
Abra a paleta de comandos selecionando Visualizar > Paleta de comandos.
Na paleta de comandos, digite Pipet e selecione o comando Pipet: Generate a FastAPI service.

Você criou um comando de extensão do VS Code que funciona com um modelo de IA da Gemma. Teste diferentes comandos e instruções para criar um fluxo de trabalho de desenvolvimento de código assistido por IA que funcione para você.

Empacotar e instalar a extensão

Você pode empacotar sua extensão como um arquivo .vsix para instalação local na sua instância do VS Code. Use a ferramenta de linha de comando vsce para gerar um arquivo de pacote .vsix do projeto de extensão, que pode ser instalado na instância do VS Code. Para detalhes sobre como empacotar sua extensão, consulte a documentação do VS Code Publicar extensões (link em inglês). Depois de concluir o pacote da extensão como um arquivo VSIX, você pode instalá-lo manualmente no VS Code.

Para instalar a extensão empacotada do VSIX:

Na sua instância do VS Code, abra o painel Extensões escolhendo Arquivo > Extensões.
No painel Extensões, selecione o menu de três pontos no canto superior direito e clique em Instalar do VSIX.
Abra o arquivo de pacote .vsix gerado no projeto de extensão para instalá-lo.

Outros recursos

Para mais detalhes sobre o código deste projeto, consulte o repositório de código do Gemma Cookbook. Se você precisar de ajuda para criar o aplicativo ou quiser colaborar com outros desenvolvedores, confira o servidor Discord da Comunidade de Desenvolvedores do Google. Para mais projetos do Build with Google AI, confira a playlist de vídeos.