Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Pesquisa Semântica de Código

Aula 6 de 18 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Pesquisar Código por Significado
  2. Indexação de um Diretório de Código
  3. Codificação e Indexação
  4. Pesquisa em Linguagem Natural
  5. Pesquisa Translinguística
  6. Pesquisa por Assinatura de Função
  7. Pontos-chave

Pesquisar Código por Significado

A pesquisa tradicional de código baseia-se em palavras-chave: escreve o nome de uma função ou uma palavra retirada de um comentário. A pesquisa semântica de código vai mais longe: encontra código pelo seu significado ou intenção, mesmo que os termos exatos não coincidam.

Com o codestral-embed, pode pesquisar código utilizando linguagem natural. Uma consulta como “função que ordena uma lista” encontrará uma implementação quicksort, mesmo que a palavra “sort” nunca apareça no código. Isto espelha a realidade diária de um programador que se junta a um projeto existente: sabe o que procura, mas não faz ideia de como a equipa anterior o designou.

Indexação de um Diretório de Código

O primeiro passo consiste em extrair e codificar todos os ficheiros ou funções de um projeto. A função abaixo percorre a árvore de diretórios e filtra as pastas que poluiriam o índice. Apenas o node_modules pode ser dez vezes maior do que o código que realmente escreveu, e nenhum dos seus ficheiros é relevante para a sua pesquisa.

import os
import numpy as np
from mistralai.client import Mistral

client = Mistral(api_key=api_key)

def extract_code_files(directory, extensions=(".py", ".js", ".ts")):
    """Extract all code files from a directory."""
    code_files = []
    for root, dirs, files in os.walk(directory):
        # Ignore irrelevant directories
        dirs[:] = [d for d in dirs if d not in ("node_modules", ".git", "__pycache__", "venv")]
        for f in files:
            if any(f.endswith(ext) for ext in extensions):
                filepath = os.path.join(root, f)
                with open(filepath, "r", encoding="utf-8", errors="ignore") as fh:
                    content = fh.read()
                if content.strip():
                    code_files.append({
                        "path": filepath,
                        "content": content[:4000],  # Truncate if too long
                    })
    return code_files

# Extract files
code_files = extract_code_files("./my-project/")
print(f"{len(code_files)} code files found")

Dois detalhes de implementação merecem atenção. Modificar dirs[:] no local não é apenas uma abreviatura; é a única forma de impedir que o os.walk desça para esses diretórios. Reatribuir a variável sem a fatiar não teria qualquer efeito. Quanto ao corte a 4.000 caracteres, isto protege-o de ficheiros monstruosos que fariam explodir o pedido, mantendo simultaneamente o cabeçalho do ficheiro — importações, definições principais — que carrega o sinal mais significativo.

Codificação e Indexação

A codificação ocorre em lotes de vinte ficheiros, com uma barra de progresso. Num repositório com várias centenas de ficheiros, este ciclo executa-se durante vários minutos. Sem um contador, não tem como distinguir um processamento lento de uma chamada bloqueada.

def index_code_files(code_files, batch_size=20):
    """Create embeddings for all code files."""
    all_embeddings = []

    for i in range(0, len(code_files), batch_size):
        batch = code_files[i:i + batch_size]
        inputs = [f["content"] for f in batch]

        response = client.embeddings.create(
            model="codestral-embed",
            inputs=inputs,
        )
        all_embeddings.extend([d.embedding for d in response.data])
        print(f"Encoded {min(i + batch_size, len(code_files))}/{len(code_files)}")

    return np.array(all_embeddings)

embeddings = index_code_files(code_files)
print(f"Index: {embeddings.shape}")

A ordem dos embeddings na matriz corresponde exatamente à ordem de code_files. Esta correspondência implícita é o pivô de tudo o que se segue: permite que um índice devolvido pela classificação aponte para um caminho de ficheiro específico.

Pesquisa em Linguagem Natural

A grande vantagem do codestral-embed é que pode pesquisar utilizando uma pergunta em francês ou em inglês. A função codifica a consulta com o mesmo modelo, calcula as similaridades em relação a todo o índice e devolve os melhores resultados top_k, juntamente com uma pré-visualização do conteúdo.

from sklearn.metrics.pairwise import cosine_similarity

def search_code(query, code_files, embeddings, top_k=5):
    """Search for code using natural language descriptions."""
    # Encode the query
    response = client.embeddings.create(
        model="codestral-embed",
        inputs=[query],
    )
    query_emb = np.array(response.data[0].embedding)

    # Calculate similarities
    sims = cosine_similarity([query_emb], embeddings)[0]

    # Top-k results
    top_indices = np.argsort(sims)[::-1][:top_k]

    results = []
    for idx in top_indices:
        results.append({
            "path": code_files[idx]["path"],
            "score": float(sims[idx]),
            "preview": code_files[idx]["content"][:200],
        })
    return results

# Natural language searches
queries = [
    "email validation function",
    "database connection",
    "HTTP error handling",
    "sorting algorithm",
]

for query in queries:
    print(f"\n--- Query: '{query}' ---")
    results = search_code(query, code_files, embeddings, top_k=3)
    for r in results:
        print(f"  [{r['score']:.3f}] {r['path']}")

O campo preview tem uma utilidade prática imediata: poupa-o de abrir cinco ficheiros para descobrir qual deles corresponde realmente. Numa integração com um editor, estes duzentos caracteres tornam-se na linha de pré-visualização apresentada sob cada resultado.

Pesquisa Translinguística

O codestral-embed compreende a lógica independentemente da linguagem. Pode pesquisar um padrão em Python e encontrar o equivalente em JavaScript:

# Search using a code example in one language...
query_python = "def authenticate(username, password): check credentials and return token"

# ...and find the equivalent in another language
results = search_code(query_python, code_files, embeddings)
# May return a .js file with a similar function

Esta capacidade é inestimável para aplicações divididas entre um backend em Python e um frontend em TypeScript, onde a mesma regra de negócio é por vezes implementada em ambos os lados. Encontrar ambas as implementações a partir de uma única consulta ajuda-o a detetar divergências antes que um bug as revele em produção.

Pesquisa por Assinatura de Função

Também pode pesquisar pela forma esperada em vez do domínio funcional. Descrever a estrutura — uma função assíncrona, uma classe, middleware, um teste — orienta a pesquisa para um tipo de objeto de código em vez de um assunto.

technical_queries = [
    "async function that fetches data from API and handles errors",
    "class with CRUD methods for database operations",
    "middleware that checks authentication token",
    "unit test for user registration",
]

for q in technical_queries:
    results = search_code(q, code_files, embeddings, top_k=2)
    print(f"\n{q}:")
    for r in results:
        print(f"  -> {r['path']} (score: {r['score']:.3f})")

Experimente estas quatro consultas no seu próprio repositório antes de avançar. Notará que os resultados degradam significativamente em ficheiros muito longos, onde o corte de 4.000 caracteres removeu a parte útil. Este é o momento de decidir se deve indexar ficheiros inteiros ou, melhor ainda, funções decompostas uma a uma.

Pontos-chave

  • O codestral-embed permite pesquisar código utilizando descrições em linguagem natural
  • A indexação envolve codificar todos os ficheiros de código em vetores
  • A pesquisa translinguística funciona: um padrão em Python encontra o equivalente em JS
  • Filtre diretórios irrelevantes (node_modules, .git, venv) durante a extração
  • Trunque ficheiros muito longos para permanecer dentro dos limites do modelo