Update README: full API table + unified model.* usage
Browse files
README.md
CHANGED
|
@@ -24,21 +24,16 @@ Built with the **SocrateX** library — a modular, easy-to-use training framewor
|
|
| 24 |
## Quick Start — Use the Pre-trained Model
|
| 25 |
|
| 26 |
```python
|
|
|
|
| 27 |
from huggingface_hub import hf_hub_download
|
| 28 |
-
from tokenizers import Tokenizer
|
| 29 |
-
import torch
|
| 30 |
-
|
| 31 |
-
# Download model files
|
| 32 |
-
model_path = hf_hub_download("ihatebaselines/Socrate", "pytorch_model.bin")
|
| 33 |
-
tok_path = hf_hub_download("ihatebaselines/Socrate", "ocr_bpe_tokenizer.json")
|
| 34 |
|
| 35 |
-
# Load
|
| 36 |
-
tokenizer = Tokenizer.from_file(tok_path)
|
| 37 |
-
|
| 38 |
-
# Load model with AutoModel (requires trust_remote_code=True)
|
| 39 |
-
from transformers import AutoModel
|
| 40 |
model = AutoModel.from_pretrained("ihatebaselines/Socrate", trust_remote_code=True)
|
| 41 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 42 |
# Run OCR on an image
|
| 43 |
results = model.predict(["your_image.jpg"], function="generate", max_iter=64)
|
| 44 |
print(results)
|
|
@@ -48,18 +43,16 @@ print(results)
|
|
| 48 |
|
| 49 |
## Quick Start — Build Your Own Custom Model (no pretrained weights)
|
| 50 |
|
| 51 |
-
|
| 52 |
-
No pretrained weights required — full control over every parameter.
|
| 53 |
|
| 54 |
```python
|
| 55 |
-
|
| 56 |
-
import torch
|
| 57 |
|
| 58 |
-
#
|
| 59 |
-
|
| 60 |
|
| 61 |
-
#
|
| 62 |
-
|
| 63 |
d_model=256,
|
| 64 |
nhead=4,
|
| 65 |
num_layers=4,
|
|
@@ -67,50 +60,80 @@ config = sx.Config(
|
|
| 67 |
pool_height=4
|
| 68 |
)
|
| 69 |
|
| 70 |
-
#
|
| 71 |
-
|
|
|
|
|
|
|
| 72 |
|
| 73 |
-
|
|
|
|
|
|
|
|
|
|
| 74 |
print(f"Your model has {total_params:,} parameters")
|
| 75 |
|
| 76 |
-
# 4.
|
| 77 |
-
images, labels =
|
| 78 |
-
dataset = sx.Makeset(images, labels, tokenizer=tokenizer)
|
| 79 |
-
sampler = sx.SmartBatchSampler(labels, batch_size=16)
|
| 80 |
|
|
|
|
|
|
|
| 81 |
from torch.utils.data import DataLoader
|
| 82 |
-
loader = DataLoader(dataset, batch_sampler=sampler)
|
| 83 |
|
| 84 |
-
|
| 85 |
-
|
| 86 |
|
| 87 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 88 |
for epoch in range(50):
|
| 89 |
loss = trainer.train_epoch()
|
| 90 |
print(f"Epoch {epoch} | Loss: {loss:.4f}")
|
| 91 |
|
| 92 |
-
#
|
| 93 |
-
results =
|
| 94 |
print(results)
|
| 95 |
```
|
| 96 |
|
| 97 |
---
|
| 98 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 99 |
## Architecture Presets
|
| 100 |
|
| 101 |
| Model | Params | Notes |
|
| 102 |
|-------|--------|-------|
|
| 103 |
-
| `
|
| 104 |
-
| `
|
| 105 |
-
| `
|
| 106 |
-
| Custom via `
|
| 107 |
|
| 108 |
---
|
| 109 |
|
| 110 |
-
## `
|
| 111 |
|
| 112 |
```python
|
| 113 |
-
|
| 114 |
d_model=640, # Transformer hidden dimension
|
| 115 |
nhead=10, # Multi-head attention heads
|
| 116 |
num_layers=12, # Number of Transformer layers
|
|
@@ -127,7 +150,7 @@ config = sx.Config(
|
|
| 127 |
## Inference Functions
|
| 128 |
|
| 129 |
```python
|
| 130 |
-
# Simple greedy generation
|
| 131 |
results = model.predict(images, function="generate", max_iter=64, temp=0.7, top_k=5, penalty=1.15)
|
| 132 |
|
| 133 |
# Faster generation (less accurate but quicker)
|
|
@@ -136,3 +159,17 @@ results = model.predict(images, function="generate_fast", max_iter=64)
|
|
| 136 |
# Beam search (most accurate)
|
| 137 |
results = model.predict(images, function="beam_search", max_iter=64, beam_width=4)
|
| 138 |
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 24 |
## Quick Start — Use the Pre-trained Model
|
| 25 |
|
| 26 |
```python
|
| 27 |
+
from transformers import AutoModel
|
| 28 |
from huggingface_hub import hf_hub_download
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 29 |
|
| 30 |
+
# Load pre-trained Socrate (159M) directly from HuggingFace
|
|
|
|
|
|
|
|
|
|
|
|
|
| 31 |
model = AutoModel.from_pretrained("ihatebaselines/Socrate", trust_remote_code=True)
|
| 32 |
|
| 33 |
+
# Load the tokenizer
|
| 34 |
+
tok_path = hf_hub_download("ihatebaselines/Socrate", "ocr_bpe_tokenizer.json")
|
| 35 |
+
tokenizer = model.make_tokenizer(tok_path)
|
| 36 |
+
|
| 37 |
# Run OCR on an image
|
| 38 |
results = model.predict(["your_image.jpg"], function="generate", max_iter=64)
|
| 39 |
print(results)
|
|
|
|
| 43 |
|
| 44 |
## Quick Start — Build Your Own Custom Model (no pretrained weights)
|
| 45 |
|
| 46 |
+
No need to install SocrateX separately. Everything is built into the model object.
|
|
|
|
| 47 |
|
| 48 |
```python
|
| 49 |
+
from transformers import AutoModel
|
|
|
|
| 50 |
|
| 51 |
+
# Load model from HuggingFace (only needed to access the class + tokenizer)
|
| 52 |
+
model = AutoModel.from_pretrained("ihatebaselines/Socrate", trust_remote_code=True)
|
| 53 |
|
| 54 |
+
# 1. Create your own architecture config
|
| 55 |
+
cfg = model.create_config(
|
| 56 |
d_model=256,
|
| 57 |
nhead=4,
|
| 58 |
num_layers=4,
|
|
|
|
| 60 |
pool_height=4
|
| 61 |
)
|
| 62 |
|
| 63 |
+
# 2. Create a tokenizer
|
| 64 |
+
tok = model.make_tokenizer() # fresh tokenizer
|
| 65 |
+
# or load an existing one:
|
| 66 |
+
# tok = model.make_tokenizer("ocr_bpe_tokenizer.json")
|
| 67 |
|
| 68 |
+
# 3. Build a brand-new model from your config (no pretrained weights)
|
| 69 |
+
my_model = model.new(config=cfg, tokenizer=tok, device="cuda")
|
| 70 |
+
|
| 71 |
+
total_params = sum(p.numel() for p in my_model.parameters())
|
| 72 |
print(f"Your model has {total_params:,} parameters")
|
| 73 |
|
| 74 |
+
# 4. Load your dataset
|
| 75 |
+
images, labels = my_model.load_data("your_label.csv")
|
|
|
|
|
|
|
| 76 |
|
| 77 |
+
# 5. Build a dataset + DataLoader
|
| 78 |
+
import torch
|
| 79 |
from torch.utils.data import DataLoader
|
|
|
|
| 80 |
|
| 81 |
+
dataset = my_model.make_dataset(images, labels)
|
| 82 |
+
loader = DataLoader(dataset, batch_size=16, shuffle=True)
|
| 83 |
|
| 84 |
+
# 6. Train
|
| 85 |
+
optimizer = torch.optim.AdamW(my_model.parameters(), lr=1e-4)
|
| 86 |
+
criterion = torch.nn.CrossEntropyLoss(ignore_index=tok.token_to_id("<pad>"))
|
| 87 |
+
|
| 88 |
+
trainer = my_model.make_trainer(loader, optimizer, criterion)
|
| 89 |
for epoch in range(50):
|
| 90 |
loss = trainer.train_epoch()
|
| 91 |
print(f"Epoch {epoch} | Loss: {loss:.4f}")
|
| 92 |
|
| 93 |
+
# 7. Run inference
|
| 94 |
+
results = my_model.predict(["test.jpg"], function="generate", max_iter=64)
|
| 95 |
print(results)
|
| 96 |
```
|
| 97 |
|
| 98 |
---
|
| 99 |
|
| 100 |
+
## Full API — All Methods on the Model Object
|
| 101 |
+
|
| 102 |
+
Once loaded with `AutoModel.from_pretrained`, the model exposes the entire SocrateX API:
|
| 103 |
+
|
| 104 |
+
| Method | Description |
|
| 105 |
+
|--------|-------------|
|
| 106 |
+
| `model.predict(images, ...)` | Run OCR inference on a list of image paths |
|
| 107 |
+
| `model.fit(dataloader, optimizer, criterion, ...)` | Train the model for N epochs |
|
| 108 |
+
| `model.make_dataset(images, labels, ...)` | Create a `Makeset` dataset object |
|
| 109 |
+
| `model.create_config(d_model, nhead, ...)` | Create a custom architecture config |
|
| 110 |
+
| `model.new(config, tokenizer, device)` | Build a new model from scratch with your config |
|
| 111 |
+
| `model.make_tokenizer(path=None)` | Load or create a BPE tokenizer |
|
| 112 |
+
| `model.make_trainer(loader, optimizer, criterion)` | Returns a `Trainer` wired to this model |
|
| 113 |
+
| `model.load_data(path)` | Load images + labels from CSV/JSON/TXT |
|
| 114 |
+
| `model.generate_data(source, count, output_dir, mode)` | Generate synthetic training data |
|
| 115 |
+
| `model.freeze_encoder()` | Freeze CNN + Encoder weights (fine-tuning) |
|
| 116 |
+
| `model.unfreeze_encoder()` | Unfreeze encoder weights |
|
| 117 |
+
| `model.load_parameters(path)` | Load weights from a `.pt` checkpoint |
|
| 118 |
+
| `model.summary()` | Print total/trainable parameter counts |
|
| 119 |
+
|
| 120 |
+
---
|
| 121 |
+
|
| 122 |
## Architecture Presets
|
| 123 |
|
| 124 |
| Model | Params | Notes |
|
| 125 |
|-------|--------|-------|
|
| 126 |
+
| `cat` | 159M | This checkpoint (d_model=640, 12 layers) |
|
| 127 |
+
| `rat` | ~80M | d_model=512, 8 layers |
|
| 128 |
+
| `mice` | ~40M | d_model=384, 6 layers |
|
| 129 |
+
| Custom via `create_config` | Your choice | Full control |
|
| 130 |
|
| 131 |
---
|
| 132 |
|
| 133 |
+
## `create_config` — All Parameters
|
| 134 |
|
| 135 |
```python
|
| 136 |
+
cfg = model.create_config(
|
| 137 |
d_model=640, # Transformer hidden dimension
|
| 138 |
nhead=10, # Multi-head attention heads
|
| 139 |
num_layers=12, # Number of Transformer layers
|
|
|
|
| 150 |
## Inference Functions
|
| 151 |
|
| 152 |
```python
|
| 153 |
+
# Simple greedy generation (fast, good quality)
|
| 154 |
results = model.predict(images, function="generate", max_iter=64, temp=0.7, top_k=5, penalty=1.15)
|
| 155 |
|
| 156 |
# Faster generation (less accurate but quicker)
|
|
|
|
| 159 |
# Beam search (most accurate)
|
| 160 |
results = model.predict(images, function="beam_search", max_iter=64, beam_width=4)
|
| 161 |
```
|
| 162 |
+
|
| 163 |
+
---
|
| 164 |
+
|
| 165 |
+
## Generate Synthetic Training Data
|
| 166 |
+
|
| 167 |
+
```python
|
| 168 |
+
model.generate_data(
|
| 169 |
+
source="https://raw.githubusercontent.com/first20hours/google-10000-english/master/google-10000-english-no-swears.txt",
|
| 170 |
+
count=1000,
|
| 171 |
+
output_dir="my_train_data",
|
| 172 |
+
mode="train" # or "test"
|
| 173 |
+
)
|
| 174 |
+
images, labels = model.load_data("my_train_data/labels.csv")
|
| 175 |
+
```
|