Pesquisa Semântica de Código
Nesta página
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