qwenlm/qwen3guard

1. This repository is primarily a model release and evaluation repo, not an application codebase. Its main purpose is to document Qwen3Guard, point users to model checkpoints, and provide scripts for benchmarking moderation behavior.

2. The core product boundary is the Qwen3Guard model family itself, released in two operational modes:

- Qwen3Guard-Gen: a generative moderation model that reads a prompt or prompt+response pair and emits a structured safety verdict.

- Qwen3Guard-Stream: a token-level streaming moderator that maintains state across incremental generation and classifies text in real time.

3. The repo’s documentation layer is centered in README.md and the attached technical report PDF. These define the safety policy, supported labels, example inputs/outputs, and the intended deployment patterns. The README is the main architecture reference for using the models correctly.

4. The generative moderation flow is:

user prompt or user prompt + assistant response → Qwen chat template → transformer inference → structured text output → regex-like parsing by the caller into Safety, Categories, and optionally Refusal.

This makes the output format part of the interface contract, not just free-form generation.

5. The streaming moderation flow is different:

tokenized conversation → initial moderation on the user turn → repeated token-by-token calls with maintained stream_state → per-token risk/category updates → stream closure.

This design is stateful and intended to sit alongside an LLM decoder, not replace it.

6. The repo clearly separates offline/local inference from serving deployment:

- Local inference uses transformers.

- Deployment for Qwen3Guard-Gen is shown through vLLM or SGLang as OpenAI-compatible endpoints.

- The README notes that streaming support in those serving stacks is still future work for Qwen3Guard-Stream.

7. The eval/ directory is the benchmarking subsystem. It contains:

- eval_gen.py for evaluating generative moderation,

- eval_stream.py for evaluating streaming moderation,

- eval/README.md for benchmark-specific instructions.

This separates evaluation logic from model usage examples.

8. Evaluation appears to be organized around the released Qwen3GuardTest benchmark, which focuses on moderation in streaming responses and reasoning-model outputs. The repo thus has a clear boundary between model inference and benchmark scoring.

9. The model’s safety taxonomy is part of the architecture because it drives both inference outputs and evaluation labels. It uses three severity levels:

Safe, Controversial, and Unsafe,

plus content categories such as Violent, PII, Suicide & Self-Harm, Copyright Violation, and Jailbreak for input-only detection.

10. The external distribution layer is important: checkpoints and datasets are hosted on Hugging Face and ModelScope. The repo itself does not store model weights; it acts as a pointer to those artifacts and as the documentation/evaluation entry point.

11. In architectural terms, the repo is a thin control plane around hosted model artifacts:

- documentation and policy definition,

- example inference flows,

- serving guidance,

- evaluation scripts.

The actual learned moderation capability lives in the remote checkpoints, while this repo defines how to invoke and assess them.