Repolode
Enviar
doofzoff

doofzoff/SIMURG

Um guard em Python apenas com numpy que detecta, durante o streaming, corrupção na decodificação de LLMs, como loops de repetição e deriva de idioma, e aborta antes que o usuário veja tokens ruins.

Ver no GitHub
Estrelas
101
Forks
15
Issues abertas
0
Último commit
há 29 dias

O que é?

O SIMURG acompanha o stream de tokens de um LLM enquanto ele é gerado e sinaliza corrupções na decodificação: colapso por repetição, deriva entre idiomas, regurgitação de texto padrão (boilerplate), lixo estrutural e marcadores de chat-template vazados. Ele segura os primeiros 350 caracteres antes de liberá-los, reverifica o stream a cada 400 caracteres e o interrompe quando um limiar calibrado é ultrapassado, para que o texto corrompido não seja mostrado ao usuário. Cada alarme vem com motivos legíveis por humanos e uma estimativa da posição em que a corrupção começou.

O núcleo roda apenas com numpy, sem necessidade de modelo ou GPU, e funciona com qualquer endpoint de chat completions compatível com a OpenAI, como vLLM, llama.cpp server, TGI, Ollama ou OpenAI. Um wrapper GuardedLLM adiciona lógica de retry e de modelo de fallback, e um caminho de autocorreção pode continuar a partir do prefixo limpo já verificado, em vez de regenerar a resposta inteira. Os limiares são calibrados com saídas limpas, e o projeto inclui um comando de retreinamento para o seu próprio tráfego e um dashboard para guarda ao vivo e replay de sessões.

O projeto deixa explícito que detecta corrupção na entrega, não erros factuais: uma frase fluente, mas falsa, não tem assinatura estatística. Ele também inclui um tier opcional com um pequeno transformer, uma camada de busca na web para verificações de fundamentação e um módulo experimental de aprendizado por feedback.

Recursos principais

  • 01Detecta loops de repetição, deriva de idioma, regurgitação, lixo estrutural e vazamento de templates em saídas em streaming.
  • 02Segura os primeiros caracteres e interrompe o stream com um limiar calibrado, para que o texto corrompido não seja mostrado.
  • 03Roda apenas com numpy, sem modelo ou GPU, e funciona com qualquer endpoint compatível com a OpenAI.
  • 04Gera motivos de alarme legíveis por humanos e a posição estimada de início da corrupção.
  • 05Faz retry ou recorre a outro modelo quando uma tentativa é sinalizada.
  • 06Permite retreinar os limiares com suas próprias saídas limpas e inclui um dashboard de guarda ao vivo.

Casos de uso

  • Proteger chatbots voltados ao usuário construídos sobre modelos quantizados ou self-hosted contra saídas degeneradas.
  • Adicionar um portão de qualidade em meio ao stream na frente de um servidor de inferência, antes que os tokens cheguem à interface.
  • Auditar e reproduzir gerações corrompidas de um modelo em produção para encontrar padrões de falha.
  • Detectar um novo modo de falha no seu próprio modelo treinando um detector personalizado com exemplos rotulados.

Início rápido

  1. 1

    Instale o pacote do PyPI

    pip install simurg
  2. 2

    Ou instale a partir do código-fonte clonando o repositório

    git clone https://github.com/doofzoff/SIMURG.git
  3. 3

    Acesse a pasta do projeto e instale em modo editável

    cd SIMURG && pip install -e .
  4. 4

    Execute o benchmark reproduzível

    python3 -m simurg.data.evaluate

Antes de usar

  • A calibração está ajustada ao benchmark sintético incluído, então você deve treinar novamente com seu próprio tráfego antes de confiar nele em produção.
  • Uma corrupção no meio do fluxo pode deixar uma cauda inválida de até cerca de 900 caracteres até que a nova tentativa a substitua; além disso, a corrupção que começa na janela hold só é totalmente bloqueada em 12 dos 21 casos do benchmark.

Tópicos

#llm#guardrails#streaming#llm-safety#hallucination-detection#anomaly-detection#openai-api#vllm#inference#online-learning

Perguntas frequentes

O que é SIMURG?
Um guard em Python apenas com numpy que detecta, durante o streaming, corrupção na decodificação de LLMs, como loops de repetição e deriva de idioma, e aborta antes que o usuário veja tokens ruins. O SIMURG acompanha o stream de tokens de um LLM enquanto ele é gerado e sinaliza corrupções na decodificação: colapso por repetição, deriva entre idiomas, regurgitação de texto padrão (boilerplate), lixo estrutural e marcadores de chat-template vazados. Ele segura os primeiros 350 caracteres antes de liberá-los, reverifica o stream a cada 400 caracteres e o interrompe quando um limiar calibrado é ultrapassado, para que o texto corrompido não seja mostrado ao usuário. Cada alarme vem com motivos legíveis por humanos e uma estimativa da posição em que a corrupção começou.
SIMURG é gratuito? Qual é a licença?
SIMURG é open source sob a licença Apache-2.0. Confira os termos da licença antes de usá-lo em produtos comerciais.
SIMURG ainda é mantido?
Manutenção ativa. O último commit de SIMURG foi em 21 de set. de 2026.
Para que posso usar SIMURG?
Proteger chatbots voltados ao usuário construídos sobre modelos quantizados ou self-hosted contra saídas degeneradas. Adicionar um portão de qualidade em meio ao stream na frente de um servidor de inferência, antes que os tokens cheguem à interface. Auditar e reproduzir gerações corrompidas de um modelo em produção para encontrar padrões de falha. Detectar um novo modo de falha no seu próprio modelo treinando um detector personalizado com exemplos rotulados.
Como instalar SIMURG?
Instale o pacote do PyPI: pip install simurg Ou instale a partir do código-fonte clonando o repositório: git clone https://github.com/doofzoff/SIMURG.git Acesse a pasta do projeto e instale em modo editável: cd SIMURG && pip install -e . Execute o benchmark reproduzível: python3 -m simurg.data.evaluate
Onde consigo SIMURG?
O código-fonte e as instruções de instalação estão no GitHub: https://github.com/doofzoff/SIMURG

Resumo gerado por IA a partir do README do projeto. As estatísticas do GitHub são atualizadas diariamente.

Projetos relacionados