---
base_model:
- google/gemma-3-1b-it
base_model_relation: quantized
license: apache-2.0
pipeline_tag: text-generation
library_name: coreml
tags:
- text-generation
- apple-silicon
- on-device
- coreml
- ios
- macos
- thestage-apple-sdk
---

# Gemma 3 1B IT (Apple Silicon)

![On-Device Apple SDK](assets/on-device-apple-sdk-banner.png)


[TheStage Apple SDK](https://github.com/TheStageAI/AppleSDK)

**Original model:** [google/gemma-3-1b-it](https://huggingface.co/google/gemma-3-1b-it) (Google)

On-device instruction-tuned Gemma 3 1B compressed and packaged by **TheStage AI** for Apple Silicon (CoreML / Neural Engine). Ships as a TheStage Apple SDK engine bundle.

> Also accepted as `TheStageAI/Gemma3-1B` in the SDK revision map.

| | |
| --- | --- |
| Parameters | **1B** |
| Chat template | Gemma3 (from bundle) |
| Runtime | TheStage Apple SDK (`TheStageLLM`) |
| HF engines | `TheStageAI/gemma-3-1b-it` |


## Overview

---

This repo hosts **CoreML / MLX engine bundles** for the TheStage Apple SDK. Point `engines_path` at the repo id; the SDK downloads, caches, and loads the engines automatically. Chat template, EOS / stop tokens, and KV-cache horizon all come from the bundle.

## System Requirements

---

| **Property** | **Value** |
| --- | --- |
| **Hardware** | Apple Silicon Mac, or physical iPhone / iPad |
| **macOS** | 15.0+ |
| **iOS** | 18.0+ |
| **Xcode** | 16.0+ |
| **Swift** | 6.0+ |
| **Flutter** (optional) | 3.24+ |

> Simulator is **not** supported — run on real Apple Silicon hardware.


## TheStage AI Access Token

---

Create a token at [app.thestage.ai](https://app.thestage.ai) and pass it to the SDK:

```swift
try await TheStageAI.shared.initialize(apiToken: "th_…")
```

```dart
await TheStageFlutterSDK.initialize(api_token: 'th_…');
```

Token is checked online in `initialize` (once per app process when reachable). Inference runs fully on-device. Offline initialize fails — reconnect and call `initialize` again.


## TheStage Apple SDK

---

Docs: [TheStage Apple SDK · LLM](https://docs.thestage.ai) · Repo: [TheStage Apple SDK](https://github.com/TheStageAI/AppleSDK)


### Installation (SwiftPM)

In Xcode: **File → Add Package Dependencies…**, paste `https://github.com/TheStageAI/AppleSDK.git`, and add the `TheStageSDK` product. Or in `Package.swift`:

```swift
.package(
    url: "https://github.com/TheStageAI/AppleSDK.git",
    exact: Version(1, 1, 0)
)
```

### Installation (Flutter / iOS)

```yaml
# pubspec.yaml
dependencies:
  thestage_apple_sdk:
    git:
      url: https://github.com/TheStageAI/AppleSDK.git
      path: plugin/thestage_apple_sdk
      ref: 1.1.0
```


### Swift — batch

```swift
import TheStageSDK

try await TheStageAI.shared.initialize(apiToken: "th_…")

let llm = try await TheStageLLM(
    engines_path: "TheStageAI/gemma-3-1b-it"
)

let result = llm.infer(
    prompt: "What is 2+2?",
    system_prompt: "You are a helpful assistant.",
    max_new_tokens: 64
)
print(result.text)
```

For sampling control, start from the bundle preset and override only what you need:

```swift
var config = llm.generation_defaults
config.max_new_tokens = 256
config.temperature = 0.7
config.top_p = 0.8
config.repetition_penalty = 1.1

let result = llm.infer(prompt: "List 5 facts about London.", config: config)
```


### Swift — streaming

```swift
for await chunk in llm.infer_stream(
    prompt: "Tell me a short story.",
    max_new_tokens: 512
) {
    if chunk.is_final {
        print("\n--- \(chunk.tokens_per_second ?? 0) tok/s ---")
    } else {
        print(chunk.text, terminator: "")
    }
}
```

### Flutter (iOS)

```dart
import 'package:thestage_apple_sdk/thestage_apple_sdk.dart';

await TheStageFlutterSDK.initialize(api_token: 'th_…');

await TheStageFlutterSDK.start_model(
  model_name: 'llm',
  engines_path: 'TheStageAI/gemma-3-1b-it',
);

final result = await TheStageFlutterSDK.infer(
  model_name: 'llm',
  input_json: {
    'prompt': 'What is 2+2?',
    'system_prompt': 'You are a helpful assistant.',
    'max_new_tokens': 64,
  },
);
print(result[0]['text']);
```

Streaming:

```dart
final stream = TheStageFlutterSDK.infer_stream(
  model_name: 'llm',
  input_json: {'prompt': 'Tell me a short story.', 'max_new_tokens': 512},
);
await for (final chunk in stream) {
  if (chunk['is_final'] == true) break;
  final delta = chunk['delta'] as String?;
  if (delta != null) stdout.write(delta);
}
```

### Inputs / outputs

| Direction | Field | Notes |
| --- | --- | --- |
| in | `prompt` | User message |
| in | `system_prompt` | Optional; bundle default if omitted |
| in | `max_new_tokens` | Cap on generated tokens |
| in | `temperature` / `top_k` / `top_p` / `min_p` / `repetition_penalty` / `seed` | Sampling; omit → bundle `generation_defaults` |
| out | `text` | Decoded reply |
| out | `tokens_per_second`, `time_to_first_token`, `stop_reason` | Metrics |

### On-device latency

Release build on **Apple M2 Max (NPU / ANE), macOS 26.2** (guidance, not an SLA). Warmed decode, **256** new tokens:

| Metric | Value |
| --- | --- |
| tok/s (medium prompt) | **83.1** |
| TTFT small → long (s) | **0.058 → 0.112** |
| Process mem (MB) | **~163** |

Always measure release builds on device.

## Acknowledgments

---

This work builds on **gemma-3-1b-it** by Google: [google/gemma-3-1b-it](https://huggingface.co/google/gemma-3-1b-it).

Gemma is provided under and subject to the Gemma Terms of Use. This Apple Silicon package is produced by TheStage AI; it is not an official Google release.

## Links

---


* __Original model__: [google/gemma-3-1b-it](https://huggingface.co/google/gemma-3-1b-it)
* __Platform__: [app.thestage.ai](https://app.thestage.ai)
* __TheStage Apple SDK__: [github.com/TheStageAI/AppleSDK](https://github.com/TheStageAI/AppleSDK)
* __Docs__: [docs.thestage.ai](https://docs.thestage.ai)
* __Subscribe for updates__: [TheStageAI X](https://x.com/TheStageAI)
* __Contact email__: contact@thestage.ai