How asii-mov/llama-guard-output-feedback works
Project Type and Purpose
• This is a research‐oriented experiment pipeline, not a user‐facing application. Its goal is to improve the input‐filtering behavior of Meta’s Llama Guard by using output‐feedback: prompts that lead to blocked outputs become negative training examples.
File Structure Analysis
• Top‐level files:
• finetuning_data_formatter.py – prepares prompt examples for fine‐tuning
• research_implementation.py – core Python module orchestrating processing, training, evaluation
• research_config.json – all hyperparameters, model paths, dataset names, output directories
• run_experiment.sh – single‐entrypoint shell script that runs “process”, “train”, “evaluate” or full pipeline
• requirements.txt – Python dependencies
• README.md – project overview and usage
Key Insights from README
• Three distinct stages (process → train → evaluate), each driven by research_implementation.py and configured by research_config.json.
• External dependencies: Hugging Face LLMs (Mistral‐7B for generation, LlamaGuard‐7b for filtering), HF CLI for authentication, dataset (e.g. lmsys/toxic-chat).
• Intermediate and final artifacts: blocked_inputs.jsonl, fine‐tuned adapter checkpoint, evaluation metrics and logs.
a. Configuration Loader
• Reads research_config.json
b. Experiment Orchestrator
• run_experiment.sh calls research_implementation.py with the requested stage
c. Data Processing (“process” stage)
• Base LLM (Mistral‐7B) generates candidate responses
• Default Llama Guard filters outputs → yields blocked prompts → write to data/blocked_inputs/blocked_inputs.jsonl
• finetuning_data_formatter transforms JSONL into LoRA‐ready datasets
d. Model Training (“train” stage)
• LoRA fine‐tuning on “unsafe” vs “safe” examples
• Uses default Llama Guard base model → produces improved adapter at training.output_dir
e. Evaluation (“evaluate” stage)
• Loads default vs improved adapters
• Runs on test set → computes precision/recall/F1 → writes to evaluation.results_dir
f. External Services
• Hugging Face Hub (model retrieval, push/pull)
• Dataset host (e.g. lmsys/toxic-chat)
Relationships and Data Flow
• Data flows:
• Config → all stages
• LLM outputs → Llama Guard filter → blocked_inputs.jsonl → formatted dataset → training module → adapter
• Adapter + test data → evaluation module → metrics
• External systems are side‐connected: Hugging Face Hub, dataset registry
Architectural Patterns and Principles
• Modular, stage‐based pipeline
• Single source of truth for config (research_config.json)
• Clear separation of concerns: data collection, fine‐tuning, evaluation
• Reusability: formatter, implementation module, shell wrapper