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

Context Biasing: Melhorar a Precisão

Aula 8 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O Problema dos Termos Especializados
  2. Utilizar o Context Biasing
  3. Construir uma Lista Eficaz
  4. Gerir o Vocabulário por Projeto
  5. O Que Funciona e o Que Não Funciona
  6. Pontos-chave

Curso atualizado em 3 de novembro de 2026 para o Voxtral 3, com base no guia Migrate from Voxtral 2 da Mistral: os modelos Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), descontinuados em 31 de outubro de 2026 e retirados em 30 de abril de 2027, são substituídos nos exemplos por voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 e voxtral-mini-tts-3-0. Principais alterações: as marcas temporais são apenas por segmento (word devolve um erro 400), a diarização é possível em tempo real, as definições da sessão em tempo real ficam bloqueadas após o primeiro bloco de áudio e as entradas context_bias são de formato livre (frases com espaços permitidas). Fontes: Migrate from Voxtral 2 · Speech to Text.

O Problema dos Termos Especializados

Os modelos de transcrição são treinados com linguagem comum. Quando o seu áudio contém nomes próprios, acrónimos, jargão técnico ou termos raros da indústria, o modelo transcreve-os frequentemente de forma incorreta: “Voxtral” torna-se “vox trail” e “RGPD” (o acrónimo francês para o Regulamento Geral sobre a Proteção de Dados da UE) surge como “RG PD”. Numa reunião de uma hora, estes erros somam dezenas, e são precisamente as palavras que queria extrair.

O context biasing resolve este problema ao fornecer ao modelo uma lista de termos esperados. O modelo ajusta então as suas probabilidades para favorecer estes termos quando os deteta no áudio. Isto não é uma substituição automática no pós-processamento; orienta a descodificação durante a transcrição. É esta nuance que permite que o resultado permaneça natural.

Utilizar o Context Biasing

O parâmetro context_bias aceita uma lista de termos: em Python, uma lista de cadeias de caracteres. Com o Voxtral 3, uma entrada pode conter espaços — um nome completo de produto como “Alder Creek Design” — e já não existe um limite rígido para o número de entradas. No entanto, as entradas partilham a janela de contexto com o áudio: um pedido que a exceda é rejeitado (erro 400), razão pela qual uma lista curta é preferível.

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

with open("reunion_tech.mp3", "rb") as f:
    response = client.audio.transcriptions.complete(
        model="voxtral-mini-transcribe-3",
        file={"content": f, "file_name": "reunion_tech.mp3"},
        context_bias=["Voxtral", "Mistral AI", "RGPD", "Kubernetes", "PostgreSQL", "FastAPI"]
    )

print(response.text)

O efeito é imediato. Sem context biasing, uma reunião de engenharia pode produzir isto:

On a déployé le nouveau service sur cubernétisse avec fast API
et la base post grès cul.

Com a lista ["Kubernetes", "FastAPI", "PostgreSQL"], a mesma frase torna-se utilizável:

On a déployé le nouveau service sur Kubernetes avec FastAPI
et la base PostgreSQL.

Fora do modo em tempo real, uma entrada pode até ser uma frase de contexto de formato livre que descreve a conversa: “Call to Northwind support regarding an order of Quillara headsets shipped from the Rotterdam warehouse.” O modelo utiliza isto para orientar o reconhecimento dos nomes que contém.

Construir uma Lista Eficaz

Quatro famílias de termos merecem um lugar. Primeiro, nomes próprios: pessoas, empresas, produtos — tudo aquilo que o modelo não tem razão para conhecer. Segundo, termos técnicos: acrónimos, nomes de tecnologias, protocolos. Terceiro, jargão da indústria específico do seu setor que não aparece nos dicionários gerais. Finalmente, nomes de locais: cidades, edifícios, salas de reuniões, frequentemente citados e raramente bem transcritos.

O conteúdo da lista depende inteiramente do contexto. Uma reunião numa startup tecnológica exige um vocabulário diferente de uma consulta médica ou de uma entrevista num escritório de advogados. Eis três listas reais para usar como modelos.

Reunião numa startup tecnológica:

context_bias = [
    "Mistral AI", "Voxtral", "Claude", "GPT-5.6",
    "Kubernetes", "PostgreSQL", "FastAPI", "Redis",
    "RGPD", "HIPAA", "SOC 2",
    "sprint", "backlog", "user story",
    "CI/CD", "Docker", "Terraform"
]

Consultório médico:

context_bias = [
    "paracétamol", "ibuprofène", "amoxicilline",
    "IRM", "scanner", "échographie",
    "glycémie", "hémoglobine", "créatinine",
    "Dr Martin", "Dr Dubois",
    "CHU Pitié-Salpêtrière"
]

Escritório de advogados:

context_bias = [
    "SARL", "SAS", "SASU",
    "article L.225-1", "Code de commerce",
    "assignation", "mise en demeure",
    "TGI", "Cour d'appel",
    "Maître Dupont", "Maître Leroy"
]

Gerir o Vocabulário por Projeto

Codificar a lista diretamente no código não é escalável quando entram em cena múltiplos clientes ou serviços. O script seguinte carrega o vocabulário a partir de um ficheiro JSON, permite adicionar termos ad hoc e deduplica o conjunto. Não impõe nenhum limite rígido, uma vez que o Voxtral 3 não tem nenhum, mas emite um aviso se a lista for demasiado longa: é isso que riska exceder a janela de contexto.

import os
import json
from pathlib import Path
from mistralai.client import Mistral

ALERT_THRESHOLD = 50  # Marcador interno: além disto, verifique o tamanho do pedido


def load_vocabulary(config_path: str) -> list[str]:
    """Carrega o vocabulário de context biasing a partir de um ficheiro JSON."""
    config = json.loads(Path(config_path).read_text(encoding="utf-8"))
    terms = list(dict.fromkeys(config.get("terms", [])))

    if len(terms) > ALERT_THRESHOLD:
        print(f"Aviso: {len(terms)} termos; uma lista longa reduz "
              f"o espaço disponível para o áudio na janela de contexto.")

    return terms

def transcribe_with_vocabulary(
    audio_path: str,
    config_path: str = None,
    additional_terms: list = None
) -> str:
    """Transcreve com context biasing opcional."""
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

    # Construir a lista de termos
    all_terms = []

    if config_path and Path(config_path).exists():
        config = json.loads(
            Path(config_path).read_text(encoding="utf-8")
        )
        all_terms.extend(config.get("terms", []))

    if additional_terms:
        all_terms.extend(additional_terms)

    # Deduplicar preservando a ordem
    all_terms = list(dict.fromkeys(all_terms))
    bias = all_terms or None

    # Transcrever
    with open(audio_path, "rb") as f:
        kwargs = {
            "model": "voxtral-mini-transcribe-3",
            "file": {"content": f, "file_name": Path(audio_path).name}
        }
        if bias:
            kwargs["context_bias"] = bias
            print(f"Context biasing ativo: {len(all_terms)} termos")

        response = client.audio.transcriptions.complete(**kwargs)

    return response.text

# Ficheiro de configuração de vocabulário vocabulaire.json
# {
#   "terms": [
#     "Mistral AI", "Voxtral", "Kubernetes",
#     "PostgreSQL", "RGPD", "Dr Martin"
#   ]
# }

# Utilização
texte = transcribe_with_vocabulary(
    "reunion.mp3",
    config_path="vocabulaire.json",
    additional_terms=["nouveau_terme", "autre_terme"]
)
print(texte)

O Que Funciona e o Que Não Funciona

O context biasing produz os melhores resultados em termos precisos e distintos: nomes próprios, acrónimos, vocabulário técnico raro. Pressupõe também que os termos fornecidos estão realmente presentes no áudio — adicionar palavras que nunca serão ditas dilui o sinal sem acrescentar valor. Uma lista de vinte a cinquenta termos bem escolhidos é suficiente na maioria das situações.

Pelo contrário, listar palavras comuns é inútil: o modelo já as reconhece bem e consome espaço útil. Frases longas funcionam mal; atenha-se a palavras ou frases curtas. Finalmente, cuidado com o reflexo de despejar todo o glossário da empresa no parâmetro: um vocabulário demasiado amplo afoga os poucos termos que realmente importavam.

Um ponto de vigilância para os seus projetos em francês: o context biasing é otimizado para inglês, e a Mistral AI qualifica o suporte para outras línguas, incluindo o francês, como experimental. Na prática, funciona corretamente para nomes próprios e acrónimos em todas as línguas, mas pode ser menos eficaz para termos comuns em línguas que não o inglês. Teste num excerto representativo antes de generalizar para um corpus inteiro.

Pontos-chave

  • O context biasing melhora o reconhecimento de termos especializados através de context_bias
  • Uma lista de termos (frases com espaços permitidas), sem limite fixo mas condicionada pela janela de contexto
  • Eficaz para: nomes próprios, acrónimos, jargão técnico, nomes de locais
  • Otimizado para inglês, suporte experimental para outras línguas
  • Prefira termos precisos que estejam realmente presentes no áudio
  • Utilize um ficheiro de configuração para gerir o vocabulário por projeto