estruturacao

estruturacao

Estruturação de textos com LLMs — extrai campos JSON conforme um schema.

Modo nuvem

Roda na infra do escritório, com os modelos servidos pelo recurso Azure OpenAI da FGV (Brazil South, Global Standard): gpt-4.1-mini (default) e gpt-5.6-luna (modelo de raciocínio, mais capaz e mais caro). Os modelos self-host em GPU A100 (gpt-oss-20b, gemma-4-26b-it) foram descontinuados por custo proibitivo no padrão de uso atual.

Modo local

Cliente OpenAI-compatível: aceita OpenAI, Azure OpenAI, Ollama (default http://localhost:11434/v1) ou qualquer servidor /v1/chat/completions. O usuário traz a própria chave/URL. Endpoints Azure (*.openai.azure.com / *.services.ai.azure.com) — como o recurso da FGV — são reconhecidos automaticamente e chamados pela API v1 (/openai/v1/); modelo_local é o nome do deployment. Desde a v0.5.0 a chamada ao LLM e a montagem do prompt vivem em labdados_core.estruturacao — o mesmo código rodado pelo backend (services/structuring), garantindo que prompt e parsing não divirjam.

.. note:: Mudança de comportamento na v0.5.0: o schema passa a ser injetado na mensagem user (junto do texto), não mais na system. Isso alinha com o backend e funciona melhor com response_format=json_schema. Se o seu prompt depender da formulação antiga, instrua o LLM via prompt_sistema ou abra uma issue.

Functions

Name	Description
estruturacao	Extrai campos estruturados (JSON) a partir de textos.

estruturacao

estruturacao.estruturacao(
    arquivos,
    *,
    schema,
    prompt_sistema='',
    saida=None,
    api_key=None,
    modelo='gpt-4.1-mini',
    coluna_texto='',
    temperatura=0.0,
    max_tokens=4096,
    local=False,
    base_url_local='http://localhost:11434/v1',
    api_key_local='ollama',
    modelo_local='llama3.1',
    client=None,
    progress=True,
)

Extrai campos estruturados (JSON) a partir de textos.

Parameters

Name	Type	Description	Default
arquivos	PathLike | list[PathLike]	.txt, .md, .docx, .csv ou .xlsx. Para CSV/XLSX, cada linha vira um documento — use coluna_texto para indicar qual coluna contém o texto a estruturar.	required
schema	dict[str, Any] | str	JSON Schema (dict) ou string JSON. Define os campos extraídos e seus tipos. Mantenha simples — campos com description ajudam muito a LLM.	required
prompt_sistema	str	Instruções de contexto (qual o tipo de documento, o que ignorar…).	''
saida	PathLike | None	Pasta de saída. Cada documento gera um .json com a extração.	None
api_key	str | None	Chave de API do escritório (modo nuvem).	None
modelo	str	"gpt-4.1-mini" (default) ou outro modelo do Azure AI Foundry da FGV: "gpt-4.1", "gpt-5-mini", "gpt-5.6-luna", "gpt-5.6-terra", "gpt-6-luna", "DeepSeek-V4-Flash", "Mistral-Large-3", "Kimi-K2.6". Os GPT-5/6 são modelos de raciocínio: extraem melhor em textos longos/difíceis, ignoram temperatura e os tokens de raciocínio contam como saída. Os modelos self-host em GPU A100 (gpt-oss-20b, gemma-4-26b-it) foram descontinuados por custo.	'gpt-4.1-mini'
coluna_texto	str	Para CSV/XLSX: nome da coluna que contém o texto a ser estruturado. Vazio = concatena todas as colunas da linha.	''
temperatura	float | None	0.0 para resultado determinístico (recomendado em extração). None omite o parâmetro — obrigatório no modo local com modelos de raciocínio (família GPT-5, ex.: gpt-5.6-luna), que só aceitam a temperatura padrão.	0.0
max_tokens	int	Tamanho máximo da resposta JSON. Aumente se o JSON estiver sendo cortado.	4096
local	bool	Se True, chama um servidor OpenAI-compatível local. Default: Ollama em http://localhost:11434/v1.	False
base_url_local	str	Configuração do servidor local. Para Azure OpenAI (ex.: o recurso da FGV), use o endpoint do recurso em base_url_local, a chave em api_key_local e o nome do deployment em modelo_local. Para Ollama, mantenha os defaults e mude apenas modelo_local (ex.: "qwen2.5:7b").	'http://localhost:11434/v1'
api_key_local	str	Configuração do servidor local. Para Azure OpenAI (ex.: o recurso da FGV), use o endpoint do recurso em base_url_local, a chave em api_key_local e o nome do deployment em modelo_local. Para Ollama, mantenha os defaults e mude apenas modelo_local (ex.: "qwen2.5:7b").	'http://localhost:11434/v1'
modelo_local	str	Configuração do servidor local. Para Azure OpenAI (ex.: o recurso da FGV), use o endpoint do recurso em base_url_local, a chave em api_key_local e o nome do deployment em modelo_local. Para Ollama, mantenha os defaults e mude apenas modelo_local (ex.: "qwen2.5:7b").	'http://localhost:11434/v1'
client	Client | None	Cliente reaproveitado (modo nuvem).	None
progress	bool	Spinner no stderr.	True

Returns

Name	Type	Description
	Path	Pasta de saída.

Examples

Modo nuvem com schema simples:

>>> import labdados
>>> labdados.estruturacao(
...     arquivos="acordaos.csv",
...     coluna_texto="ementa",
...     api_key="sk_lab_...",
...     prompt_sistema="Você está extraindo decisões judiciais sobre direito do consumidor.",
...     schema={
...         "type": "object",
...         "properties": {
...             "autor": {"type": "string"},
...             "reu": {"type": "string"},
...             "valor_causa": {"type": "number"},
...             "procedente": {"type": "boolean"},
...         },
...         "required": ["autor", "reu"],
...     },
... )

Modo local chamando direto um recurso Azure OpenAI (ex.: um deployment de gpt-5.6-luna — modelo de raciocínio, por isso temperatura=None):

>>> import os
>>> labdados.estruturacao(
...     arquivos="textos/",
...     schema={"type": "object", "properties": {"resumo": {"type": "string"}}},
...     local=True,
...     base_url_local=os.environ["AZURE_OPENAI_ENDPOINT"],  # https://<recurso>.openai.azure.com/
...     api_key_local=os.environ["AZURE_OPENAI_KEY"],
...     modelo_local="<nome-do-deployment>",
...     temperatura=None,
... )

Modo local com Ollama:

>>> labdados.estruturacao(
...     arquivos="textos/",
...     schema={"type": "object", "properties": {"resumo": {"type": "string"}}},
...     local=True,
...     modelo_local="qwen2.5:7b",
... )