embeddings

embeddings

Embeddings de textos — transforma documentos em vetores numéricos.

Os vetores servem para busca semântica, agrupamento e classificação: textos de sentido parecido ficam com vetores próximos.

Modo nuvem (default)

Faz upload dos arquivos, calcula os vetores no escritório com um modelo do Azure AI Foundry da FGV (text-embedding-3-small por padrão) e extrai o resultado na pasta saida.

Modo local (local=True)

Roda sentence-transformers na própria máquina (pip install labdados[embeddings-local]) ou, com base_url_local, qualquer servidor OpenAI-compatível (Ollama, OpenAI, um recurso Azure). Leitura, corte em trechos e formato de saída vêm de labdados_core.embeddings — a mesma rotina do serviço do escritório.

Saída (nos dois modos)

• embeddings.parquet — um trecho por linha: arquivo, doc_id, chunk, texto, embedding (lista de floats);
• chunks.csv — os mesmos trechos sem os vetores;
• _reproducibilidade/parametros.json — modelo, tamanho do trecho etc.

Functions

Name	Description
embeddings	Calcula embeddings de textos.

embeddings

embeddings.embeddings(
    arquivos,
    *,
    saida=None,
    api_key=None,
    modelo='text-embedding-3-small',
    coluna_texto='',
    max_chars=MAX_CHARS_PADRAO,
    sobreposicao=SOBREPOSICAO_PADRAO,
    local=False,
    modelo_local=None,
    base_url_local=None,
    api_key_local=None,
    dataframe=False,
    client=None,
    progress=True,
)

Calcula embeddings de textos.

Parameters

Name	Type	Description	Default
arquivos	PathLike | list[PathLike]	.txt, .md, .docx, .csv ou .xlsx (arquivo, lista ou pasta). Em CSV/XLSX, cada linha vira um documento.	required
saida	PathLike | None	Pasta de saída. Default: ./resultados_labdados/.	None
api_key	str | None	Chave de API do escritório (modo nuvem).	None
modelo	str	Modo nuvem (Azure AI Foundry da FGV): "text-embedding-3-small" (default, o mais barato), "text-embedding-3-large", "embed-v-4-0" ou "Cohere-embed-v3-multilingual" (Cohere são multilíngues). Use o mesmo modelo para todos os textos que serão comparados — vetores de modelos diferentes não são comparáveis.	'text-embedding-3-small'
coluna_texto	str	CSV/XLSX: coluna com o texto. Vazio = concatena todas as colunas.	''
max_chars	int	Textos longos são cortados em trechos de até max_chars caracteres (default 2000, ~500 tokens), com sobreposicao caracteres repetidos entre trechos vizinhos. Cada trecho vira um vetor.	MAX_CHARS_PADRAO
sobreposicao	int	Textos longos são cortados em trechos de até max_chars caracteres (default 2000, ~500 tokens), com sobreposicao caracteres repetidos entre trechos vizinhos. Cada trecho vira um vetor.	MAX_CHARS_PADRAO
local	bool	Se True, calcula na própria máquina.	False
modelo_local	str | None	Modo local: modelo do sentence-transformers (default paraphrase-multilingual-MiniLM-L12-v2) ou, com base_url_local, o nome do modelo/deployment no servidor.	None
base_url_local	str | None	Servidor OpenAI-compatível para o modo local (ex.: "http://localhost:11434/v1" no Ollama, ou o endpoint /openai/v1/ de um recurso Azure). Sem base_url_local, usa sentence-transformers.	None
api_key_local	str | None	Servidor OpenAI-compatível para o modo local (ex.: "http://localhost:11434/v1" no Ollama, ou o endpoint /openai/v1/ de um recurso Azure). Sem base_url_local, usa sentence-transformers.	None
dataframe	bool	Se True, devolve um pandas.DataFrame lido do embeddings.parquet em vez do caminho da pasta (requer pandas e pyarrow).	False
client	Client | None	Cliente reaproveitado (modo nuvem).	None
progress	bool	Spinner no stderr.	True

Returns

Name	Type	Description
	Path | pandas.DataFrame	Pasta de saída, ou o DataFrame com os trechos e vetores.

Examples

>>> import labdados
>>> df = labdados.embeddings("acordaos.csv", coluna_texto="ementa", dataframe=True)
>>> df[["arquivo", "doc_id", "texto"]].head()

Modo local com sentence-transformers:

>>> labdados.embeddings("textos/", local=True)