README.md

---
language:
- zh
- en
tags:
- affective-computing
- emotion-analysis
- system-one
- pad-model
- onnx
- pytorch
license: mit
pipeline_tag: text-classification
---

# Vibrato: A Complete System One Model for Emotion

<p align="center">
  <a href="https://github.com/corolin/vibrato"><img src="https://img.shields.io/badge/GitHub-corolin/vibrato-blue?logo=github"></a>
  <a href="https://vibrato.syrkos.com"><img src="https://img.shields.io/badge/🌐_Website-Global-blue.svg"></a>
  <a href="https://vibrato.syrkos.cn"><img src="https://img.shields.io/badge/🇨🇳_Website-China-red.svg"></a>
  <a href="https://modelscope.cn/models/corolin/vibrato"><img src="https://img.shields.io/badge/ModelScope-魔搭-624aff.svg"></a>
  <img src="https://img.shields.io/badge/License-MIT-green.svg">
  <img src="https://img.shields.io/badge/ONNX-Ready-orange.svg">
</p>

**Vibrato** is a standalone, general-purpose **System One (Jev-class) model** that performs emotion reading as typed decisions. In a single forward pass over a sequence of dialog messages, Vibrato emits **calibrated probability distributions**:
- **3 × 9-bin Likert PAD distributions** (Pleasure, Arousal, Dominance)
- **OCC-22 ranked emotion categories**
- **Pragmatic behavioral flags (Nouls)**: `suppressed` (irony/repression) & `directed_at_me` (attribution target)
- **Confidence score** for automatic escalation to heavy LLMs

> *“In a string instrument, vibrato is how emotion travels through the note.”*

---

## ⚡ Performance Matrix

| Deployment | Hardware | Latency | Memory / Disk | Use Case |
|---|---|---|---|---|
| **Vibrato v6 int8 (Fast Head)** | CPU (1 thread) | **2.97 ~ 4.39 ms** | 2.2 MB | High-throughput streaming, zero external backbone |
| **Vibrato + GPU Head** | GPU | **1.92 ms** | 7.4 MB | Real-time chat servers |
| **e5s Bundle (All-in-one)** | CPU (1 thread) | **~15 ms** | 85 MB | Full offline affective computing, desktop AI |
| **Full BGE-M3 Backbone** | GPU | **~16 ms** | 569 MB | Maximum subtlety on affective nuance |

---

## 📦 Model Artifacts in this Repository

- `models/vibrato_v6_int8.onnx`: 1.86M judgment head quantized to INT8 (2.2 MB).
- `models/vibrato_v6_fp32.onnx`: Full precision judgment head (7.4 MB, bitwise-identical to PyTorch).
- `models/vibrato_e5s_int8.onnx`: Adapted judgment head for e5-small (2.1 MB).
- `models/e5s_int8.onnx`: Multilingual e5-small embedding backbone quantized to INT8 (118 MB).
- `checkpoints/vibrato_v6.pt` & `checkpoints/vibrato_e5s.pt`: Original PyTorch model weights.
- `vocab.json` & `tokenizer/`: Char-level mapping and subword tokenizer.

---

## 🚀 Quickstart

### 1. Installation

```bash
pip install onnxruntime tokenizers numpy
```

### 2. Run Inference

Clone or download this repo, then execute:

```bash
python run_inference.py
```

Or inside Python:

```python
from run_inference import load_e5s, score_messages

vocab, tok, head, backbone = load_e5s()

messages = [
    {"role": "user", "message": "今天累死啦，快抱抱"}
]

pad, family, nouls, conf = score_messages(messages, vocab, head, backbone=backbone, tok=tok)

print("PAD:", pad)          # [Pleasure, Arousal, Dominance] in [-1.0, +1.0]
print("Family:", family)    # e.g., 'affectionate'
print("Nouls:", nouls)      # {'suppressed': bool, 'directed_at_me': bool}
print("Confidence:", conf)  # [0.0, 1.0]
```

---

## 🔗 Links

- **GitHub Repository**: [corolin/vibrato](https://github.com/corolin/vibrato)
- **ModelScope**: [corolin/vibrato](https://modelscope.cn/models/corolin/vibrato)
- **Global Landing Page**: [https://vibrato.syrkos.com](https://vibrato.syrkos.com)
- **China Landing Page**: [https://vibrato.syrkos.cn](https://vibrato.syrkos.cn)