Indexação de Codebase

A Indexação de Codebase habilita a busca semântica de código em todo o seu projeto usando embeddings de IA. Em vez de buscar correspondências exatas de texto, ela compreende o significado das suas consultas, ajudando o AI Cockpit a encontrar código relevante mesmo quando você não conhece nomes específicos de funções ou localizações de arquivos.

O que ela faz

Quando habilitada, o sistema de indexação:

1. Analisa seu código usando Tree-sitter para identificar blocos semânticos (funções, classes, métodos)
2. Cria embeddings de cada bloco de código usando modelos de IA
3. Armazena vetores em um banco de dados Qdrant para busca rápida por similaridade
4. Disponibiliza a ferramenta codebase_search para o AI Cockpit realizar descoberta inteligente de código

Isso permite consultas em linguagem natural como "lógica de autenticação de usuário" ou "tratamento de conexão com banco de dados" para encontrar código relevante em todo o seu projeto.

Principais Benefícios

• Busca Semântica: Encontre código pelo significado, não apenas por palavras-chave
• Melhor Compreensão pela IA: O AI Cockpit consegue compreender e trabalhar melhor com sua base de código
• Descoberta entre Projetos: Busque em todos os arquivos, não apenas nos que estão abertos
• Reconhecimento de Padrões: Localize implementações similares e padrões de código

Requisitos de Configuração

Provedor de Embeddings

Escolha uma dessas opções para gerar embeddings:

OpenAI (Recomendado)

• Requer chave de API da OpenAI
• Suporta todos os modelos de embedding da OpenAI
• Padrão: text-embedding-3-small
• Processa até 100.000 tokens por lote

Gemini

• Requer chave de API do Google AI
• Suporta modelos de embedding do Gemini, incluindo gemini-embedding-001
• Alternativa econômica à OpenAI
• Embeddings de alta qualidade para compreensão de código

Ollama (Local)

• Requer instalação local do Ollama
• Sem custos de API ou dependência de internet
• Suporta qualquer modelo de embedding compatível com Ollama
• Requer configuração da URL base do Ollama

Banco de Dados Vetorial

O Qdrant é necessário para armazenar e buscar embeddings:

• Local: http://localhost:6333 (recomendado para testes)
• Nuvem: Qdrant Cloud ou instância auto-hospedada
• Autenticação: Chave de API opcional para implantações seguras

Configurando o Qdrant

Configuração Local Rápida

Usando Docker:

docker run -p 6333:6333 qdrant/qdrant

Usando Docker Compose:

version: "3.8"
services:
    qdrant:
        image: qdrant/qdrant
        ports:
            - "6333:6333"
        volumes:
            - qdrant_storage:/qdrant/storage
volumes:
    qdrant_storage:

Implantação em Produção

Para uso em equipe ou produção:

• Qdrant Cloud - Serviço gerenciado
• Auto-hospedado na AWS, GCP ou Azure
• Servidor local com acesso à rede para compartilhamento em equipe

Configuração

1. Abra as configurações do AI Cockpit (ícone )
2. Navegue até a seção Indexação de Codebase
3. Habilite "Habilitar Indexação de Codebase" usando o botão de alternância
4. Configure seu provedor de embeddings:
   • OpenAI: Insira a chave de API e selecione o modelo
   • Gemini: Insira a chave de API do Google AI e selecione o modelo de embedding
   • Ollama: Insira a URL base e selecione o modelo
5. Defina a URL do Qdrant e a chave de API opcional
6. Configure os Resultados Máximos de Busca (padrão: 20, intervalo: 1-100)
7. Clique em Salvar para iniciar a indexação inicial

Botão de Habilitar/Desabilitar

O recurso de indexação de codebase inclui um botão de alternância conveniente que permite:

• Habilitar: Iniciar a indexação da sua base de código e disponibilizar a ferramenta de busca
• Desabilitar: Parar a indexação, pausar o monitoramento de arquivos e desabilitar a funcionalidade de busca
• Preservar Configurações: Sua configuração permanece salva ao desabilitar

Esse botão é útil para desabilitar temporariamente a indexação durante trabalho de desenvolvimento intensivo ou ao trabalhar com bases de código sensíveis.

Entendendo o Status do Índice

A interface mostra o status em tempo real com indicadores de cor:

• Standby (Cinza): Não está em execução, aguardando configuração
• Indexando (Amarelo): Processando arquivos atualmente
• Indexado (Verde): Atualizado e pronto para buscas
• Erro (Vermelho): Estado de falha que requer atenção

Como os Arquivos São Processados

Análise Inteligente de Código

• Integração com Tree-sitter: Usa análise AST para identificar blocos semânticos de código
• Suporte a Linguagens: Todas as linguagens suportadas pelo Tree-sitter
• Suporte a Markdown: Suporte completo para arquivos markdown e documentação
• Fallback: Divisão por linhas para tipos de arquivo não suportados
• Tamanho dos Blocos:
  • Mínimo: 100 caracteres
  • Máximo: 1.000 caracteres
  • Divide funções grandes de forma inteligente

Filtragem Automática de Arquivos

O indexador exclui automaticamente:

• Arquivos binários e imagens
• Arquivos grandes (>1MB)
• Repositórios Git (pastas .git)
• Dependências (node_modules, vendor, etc.)
• Arquivos que correspondem aos padrões .gitignore e .kilocodeignore

Atualizações Incrementais

• Monitoramento de Arquivos: Monitora o workspace em busca de alterações
• Atualizações Inteligentes: Reprocessa apenas os arquivos modificados
• Cache Baseado em Hash: Evita reprocessar conteúdo não alterado
• Troca de Branch: Lida automaticamente com mudanças de branch do Git

Boas Práticas

Seleção de Modelo

Para OpenAI:

• text-embedding-3-small: Melhor equilíbrio entre desempenho e custo
• text-embedding-3-large: Maior precisão, 5x mais caro
• text-embedding-ada-002: Modelo legado, menor custo

Para Ollama:

• mxbai-embed-large: O maior e mais qualificado modelo de embedding.
• nomic-embed-text: Melhor equilíbrio entre desempenho e qualidade de embedding.
• all-minilm: Modelo compacto com menor qualidade, mas desempenho mais rápido.

Considerações de Segurança

• Chaves de API: Armazenadas com segurança no armazenamento criptografado do VS Code
• Privacidade do Código: Apenas pequenos trechos de código são enviados para embedding (não arquivos completos)
• Processamento Local: Toda a análise acontece localmente
• Segurança do Qdrant: Use autenticação para implantações em produção

Limitações Atuais

• Tamanho de Arquivo: Máximo de 1MB por arquivo
• Workspace Único: Um workspace por vez
• Dependências: Requer serviços externos (provedor de embeddings + Qdrant)
• Cobertura de Linguagens: Limitada às linguagens suportadas pelo Tree-sitter para análise otimizada

Usando o Recurso de Busca

Uma vez indexado, o AI Cockpit pode usar a ferramenta codebase_search para encontrar código relevante:

Exemplos de Consultas:

• "Como a autenticação de usuário é tratada?"
• "Configuração de conexão com banco de dados"
• "Padrões de tratamento de erros"
• "Definições de endpoints de API"

A ferramenta fornece ao AI Cockpit:

• Trechos de código relevantes (até o limite máximo de resultados configurado)
• Caminhos de arquivo e números de linha
• Pontuações de similaridade
• Informações contextuais

Configuração dos Resultados de Busca

Você pode controlar o número de resultados de busca retornados ajustando a configuração Resultados Máximos de Busca:

• Padrão: 20 resultados
• Intervalo: 1-100 resultados
• Desempenho: Valores menores melhoram a velocidade de resposta
• Abrangência: Valores maiores fornecem mais contexto, mas podem tornar as respostas mais lentas

Privacidade e Segurança

• O código permanece local: Apenas pequenos trechos de código são enviados para embedding
• Embeddings são numéricos: Não são representações legíveis por humanos
• Armazenamento seguro: Chaves de API criptografadas no armazenamento do VS Code
• Opção local: Use o Ollama para processamento completamente local
• Controle de acesso: Respeita as permissões de arquivo existentes

Melhorias Futuras

Melhorias planejadas:

• Provedores de embeddings adicionais
• Indexação de múltiplos workspaces
• Opções aprimoradas de filtragem e configuração
• Capacidades de compartilhamento em equipe
• Integração com a busca nativa do VS Code