Caso de Utilização: Embeddings de Código
Nesta página
Para Além da Pesquisa
Os embeddings de código não servem apenas para pesquisa semântica. Eles desbloqueiam aplicações avançadas: análise de repositórios, agrupamento (clustering), detecção de duplicados e assistentes de desenvolvimento. Nesta lição, irá explorar estes casos de uso com código Python concreto.
Estes quatro casos de uso partilham uma característica comum: aproveitam a geometria do índice em vez de uma consulta. Assim que os seus ficheiros são colocados no espaço vetorial, as suas posições relativas contam uma história sobre o próprio projeto: o que se assemelha a quê, o que se repete e o que se destaca.
Análise de Repositórios
Analise a estrutura semântica de um projeto para compreender como o código está organizado. O K-Means agrupa ficheiros em cinco famílias com base na sua proximidade vetorial, sem nunca olhar para a árvore de pastas. O resultado é frequentemente instrutivo: num projeto desorganizado, verá ficheiros de diretórios muito diferentes aterrar no mesmo cluster porque, na realidade, tratam do mesmo assunto.
import numpy as np
from sklearn.cluster import KMeans
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
def analyze_repo(code_files, n_clusters=5):
"""Analyze the semantic structure of a repository."""
# Encode all files
inputs = [f["content"][:3000] for f in code_files]
response = client.embeddings.create(
model="codestral-embed",
inputs=inputs,
)
embeddings = np.array([d.embedding for d in response.data])
# K-Means Clustering
kmeans = KMeans(n_clusters=n_clusters, random_state=42, n_init=10)
labels = kmeans.fit_predict(embeddings)
# Group files by cluster
clusters = {}
for i, label in enumerate(labels):
if label not in clusters:
clusters[label] = []
clusters[label].append(code_files[i]["path"])
return clusters
# Usage
clusters = analyze_repo(code_files, n_clusters=5)
for cluster_id, files in clusters.items():
print(f"\nCluster {cluster_id} ({len(files)} files):")
for f in files[:5]:
print(f" - {f}")
O parâmetro random_state=42 fixa a inicialização: sem ele, duas execuções sucessivas produziriam números de cluster diferentes, tornando impossível comparar análises ao longo do tempo.
Deteção de Duplicados
Identifique código duplicado ou quase duplicado na sua base de código. Ao contrário de uma ferramenta de deteção clássica que compara texto, esta abordagem também deteta duplicações reescritas — o ficheiro copiado de um módulo para outro, renomeado, com variáveis diferentes mas a mesma lógica.
from sklearn.metrics.pairwise import cosine_similarity
def find_duplicates(code_files, embeddings, threshold=0.95):
"""Find pairs of near-identical files."""
sim_matrix = cosine_similarity(embeddings)
duplicates = []
for i in range(len(code_files)):
for j in range(i + 1, len(code_files)):
if sim_matrix[i][j] >= threshold:
duplicates.append({
"file_a": code_files[i]["path"],
"file_b": code_files[j]["path"],
"similarity": float(sim_matrix[i][j]),
})
# Sort by decreasing similarity
duplicates.sort(key=lambda x: x["similarity"], reverse=True)
return duplicates
# Find duplicates
dupes = find_duplicates(code_files, embeddings, threshold=0.92)
print(f"{len(dupes)} potential duplicate pairs found:")
for d in dupes[:10]:
print(f" {d['similarity']:.3f} : {d['file_a']} <-> {d['file_b']}")
O ciclo interno começa em i + 1 para comparar cada par apenas uma vez. Tenha cuidado com o custo, no entanto: a matriz de similaridade é quadrática e, além de alguns milhares de ficheiros, terá de mudar para um índice aproximado em vez de um cálculo exaustivo. Baixar o limiar de 0,95 para 0,92 alarga a rede para duplicações retrabalhadas, ao custo de alguns falsos positivos que terá de filtrar manualmente.
Agrupamento por Funcionalidade
O K-Means exige que conheça o número de grupos antecipadamente, o que raramente acontece quando se descobre um projeto. O DBSCAN resolve esta limitação: determina ele próprio o número de grupos e, crucialmente, permite que um ficheiro não pertença a nenhum — que é o significado do rótulo «Unclassified» no código abaixo.
from sklearn.cluster import DBSCAN
def cluster_by_functionality(code_files, embeddings, eps=0.3, min_samples=2):
"""Group code by functionality using DBSCAN."""
# DBSCAN on cosine distances
distance_matrix = 1 - cosine_similarity(embeddings)
clustering = DBSCAN(eps=eps, min_samples=min_samples, metric="precomputed")
labels = clustering.fit_predict(distance_matrix)
# Organize by cluster
groups = {}
for i, label in enumerate(labels):
group_name = f"Group {label}" if label >= 0 else "Unclassified"
if group_name not in groups:
groups[group_name] = []
groups[group_name].append(code_files[i]["path"])
return groups
groups = cluster_by_functionality(code_files, embeddings)
for name, files in groups.items():
print(f"\n{name} ({len(files)} files):")
for f in files[:3]:
print(f" - {f}")
A conversão via 1 - cosine_similarity transforma similaridade em distância, o formato que o DBSCAN espera com metric="precomputed". O parâmetro eps=0.3 significa, portanto, que dois ficheiros são vizinhos a partir de uma similaridade de cosseno de 0,7.
Assistente de Código Contextual
Este último exemplo reúne os blocos de construção anteriores num verdadeiro sistema RAG para código: pesquisa de ficheiros relevantes, construção de um contexto e, em seguida, chamada ao LLM. O limiar de 0,5 filtra a montante — é melhor fornecer ao modelo dois ficheiros verdadeiramente relacionados com a pergunta do que três, sendo um deles fora de tópico e capaz de o induzir em erro.
def code_assistant(question, code_files, embeddings, top_k=3):
"""Find relevant code to answer a question."""
# Encode the question
response = client.embeddings.create(
model="codestral-embed",
inputs=[question],
)
query_emb = np.array(response.data[0].embedding)
# Find the most relevant code
sims = cosine_similarity([query_emb], embeddings)[0]
top_indices = np.argsort(sims)[::-1][:top_k]
context_parts = []
for idx in top_indices:
if sims[idx] > 0.5: # Minimum threshold
context_parts.append(
f"# File: {code_files[idx]['path']}\n"
f"{code_files[idx]['content'][:1500]}"
)
context = "\n\n---\n\n".join(context_parts)
# Build the prompt for the LLM
prompt = f"""Here is relevant code from our project:
{context}
Developer question: {question}
Answer based on the code above."""
# Call the LLM with context
chat_response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}],
)
return chat_response.choices[0].message.content
# Usage
answer = code_assistant(
"How does authentication work in this project?",
code_files,
embeddings,
)
print(answer)
O caminho do ficheiro é injetado como um comentário acima de cada excerto. Isto não é decorativo: o modelo utiliza-o para citar as suas fontes e o programador que lê a resposta sabe imediatamente para onde ir verificar.
Métricas de Qualidade de Código
Por fim, os embeddings ajudam a detetar o que se destaca como invulgar. A função calcula o centroide do índice — o «ficheiro médio» do projeto — e mede o desvio de cada um. Um z-score superior a 2 sinaliza um ficheiro que não se assemelha a nenhum outro: por vezes, um pedaço de código gerado ou copiado do exterior; outras vezes, simplesmente o único ficheiro escrito num estilo antigo. Em ambos os casos, é um bom candidato para revisão.
def detect_outliers(code_files, embeddings, threshold=2.0):
"""Detect atypical code files."""
# Calculate the centroid (mean vector)
centroid = embeddings.mean(axis=0)
# Distance of each file to the centroid
distances = np.linalg.norm(embeddings - centroid, axis=1)
# Files beyond N standard deviations
mean_dist = distances.mean()
std_dist = distances.std()
outliers = []
for i, dist in enumerate(distances):
z_score = (dist - mean_dist) / std_dist
if z_score > threshold:
outliers.append({
"path": code_files[i]["path"],
"z_score": float(z_score),
})
outliers.sort(key=lambda x: x["z_score"], reverse=True)
return outliers
outliers = detect_outliers(code_files, embeddings)
print(f"{len(outliers)} atypical files:")
for o in outliers:
print(f" z={o['z_score']:.2f} : {o['path']}")
Lembre-se de que «atípico» não significa «mau». A ferramenta fornece-lhe uma lista de ficheiros para observar, não um veredito: é um ponto de partida para revisão humana, nunca uma métrica para exibir num painel de qualidade.
Pontos-chave
- Os embeddings de código permitem o agrupamento automático por funcionalidade
- A deteção de duplicados utiliza um limiar de similaridade de cosseno (0,92–0,95)
- Um assistente de código combina pesquisa semântica com um LLM para RAG de código
- Ficheiros atípicos (outliers) podem sinalizar código que necessita de revisão
- O DBSCAN é preferível ao K-Means quando o número de grupos é desconhecido