The Ramalama project's goal is to make working with AI boring through the use of OCI containers.
On first run Ramalama inspects your system for GPU support, falling back to CPU support if no GPUs are present. It then uses container engines like Podman or Docker to pull the appropriate OCI image with all of the software necessary to run an AI Model for your systems setup. This eliminates the need for the user to configure the system for AI themselves. After the initialization, Ramalama will run the AI Models within a container based on the OCI image.
Ramalama supports multiple AI model registries types called transports. Supported transports:
| Transports | Web Site |
|---|---|
| HuggingFace | huggingface.co |
| Ollama | ollama.com |
| OCI Container Registries | opencontainers.org |
Examples: quay.io, Docker Hub, and Artifactory |
The ramalama uses the Ollama registry transport by default. Use the RAMALAMA_TRANSPORTS environment variable to modify the default. export RAMALAMA_TRANSPORT=huggingface Changes RamaLama to use huggingface transport.
Individual model transports can be modifies when specifying a model via the huggingface://, oci://, or ollama:// prefix.
ramalama pull huggingface://afrideva/Tiny-Vicuna-1B-GGUF/tiny-vicuna-1b.q2_k.gguf
To make it easier for users, ramalama uses shortname files, which container alias names for fully specified AI Models allowing users to specify the shorter names when referring to models. ramalama reads shortnames.conf files if they exist . These files contain a list of name value pairs for specification of the model. The following table specifies the order which Ramama reads the files . Any duplicate names that exist override previously defined shortnames.
| Shortnames type | Path |
|---|---|
| Distribution | /usr/share/ramalama/shortnames.conf |
| Administrators | /etc/ramamala/shortnames.conf |
| Users | $HOME/.config/ramalama/shortnames.conf |
$ cat /usr/share/ramalama/shortnames.conf
[shortnames]
"tiny" = "ollama://tinyllama"
"granite" = "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf"
"granite:7b" = "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf"
"ibm/granite" = "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf"
"merlinite" = "huggingface://instructlab/merlinite-7b-lab-GGUF/merlinite-7b-lab-Q4_K_M.gguf"
"merlinite:7b" = "huggingface://instructlab/merlinite-7b-lab-GGUF/merlinite-7b-lab-Q4_K_M.gguf"
...
Install Ramalama by running this one-liner (on macOS run without sudo):
Linux:
curl -fsSL https://raw.githubusercontent.com/containers/ramalama/s/install.py | sudo python3
macOS:
curl -fsSL https://raw.githubusercontent.com/containers/ramalama/s/install.py | python3
| Hardware | Enabled |
|---|---|
| CPU | ✅ |
| Apple Silicon GPU (macOS) | ✅ |
| Apple Silicon GPU (podman-machine) | ❌ |
| Nvidia GPU (cuda) | ❌ |
| AMD GPU (rocm) | ❌ |
| Command | Description |
|---|---|
| ramalama(1) | Primary ramalama man page. |
| ramalama-containers(1) | List all ramalama containers. |
| ramalama-list(1) | List all AI models in local storage. |
| ramalama-login(1) | Login to remote model registry. |
| ramalama-logout(1) | Logout from remote model registry. |
| ramalama-pull(1) | Pull AI Models into local storage. |
| ramalama-push(1) | Push AI Model (OCI-only at present) |
| ramalama-rm(1) | Remove specified AI Model from local storage. |
| ramalama-run(1) | Run specified AI Model as a chatbot. |
| ramalama-serve(1) | Serve specified AI Model as an API server. |
| ramalama-stop(1) | Stop ramalaman container running an AI Model. |
| ramalama-version(1) | Display the ramalama version. |
You can run a chatbot on a model using the run command. By default, it pulls from the ollama registry.
Note: Ramalama will inspect your machine for native GPU support and then will use a container engine like Podman to pull an OCI container image with the appropriate code and libraries to run the AI Model. This can take a long time to setup, but only on the first run.
$ ramalama run instructlab/merlinite-7b-lab
Copying blob 5448ec8c0696 [--------------------------------------] 0.0b / 63.6MiB (skipped: 0.0b = 0.00%)
Copying blob cbd7e392a514 [--------------------------------------] 0.0b / 65.3MiB (skipped: 0.0b = 0.00%)
Copying blob 5d6c72bcd967 done 208.5MiB / 208.5MiB (skipped: 0.0b = 0.00%)
Copying blob 9ccfa45da380 [--------------------------------------] 0.0b / 7.6MiB (skipped: 0.0b = 0.00%)
Copying blob 4472627772b1 [--------------------------------------] 0.0b / 120.0b (skipped: 0.0b = 0.00%)
>
After the initial container image has been downloaded, you can interact with different models, using the container image.
$ ramalama run granite-code
> Write a hello world application in python
print("Hello World")
In a different terminal window see the running podman container.
$ podman ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
91df4a39a360 quay.io/ramalama/ramalama:latest /home/dwalsh/rama... 4 minutes ago Up 4 minutes gifted_volhard
You can list all models pulled into local storage.
$ ramalama list
NAME MODIFIED SIZE
ollama://tiny-llm:latest 16 hours ago 5.5M
huggingface://afrideva/Tiny-Vicuna-1B-GGUF/tiny-vicuna-1b.q2_k.gguf 14 hours ago 460M
ollama://granite-code:3b 5 days ago 1.9G
ollama://granite-code:latest 1 day ago 1.9G
ollama://moondream:latest 6 days ago 791M
You can pull a model using the pull command. By default, it pulls from the ollama registry.
$ ramalama pull granite-code
################################################### 32.5%
You can serve multiple models using the serve command. By default, it pulls from the ollama registry.
$ ramalama serve --name mylama llama3
You can stop a running model if it is running in a container.
$ ramalama stop mylama
+---------------------------+
| |
| ramalama run granite-code |
| |
+-------+-------------------+
|
|
| +------------------+
| | Pull model layer |
+----------------------------------------->| granite-code |
+------------------+
| Repo options: |
+-+-------+------+-+
| | |
v v v
+---------+ +------+ +----------+
| Hugging | | quay | | Ollama |
| Face | | | | Registry |
+-------+-+ +---+--+ +-+--------+
| | |
v v v
+------------------+
| Start with |
| llama.cpp and |
| granite-code |
| model |
+------------------+
Regard this alpha, everything is under development, so expect breaking changes, luckily it's easy to reset everything and re-install:
rm -rf /var/lib/ramalama # only required if running as root user
rm -rf $HOME/.local/share/ramalama
and install again.
This project wouldn't be possible without the help of other projects like:
llama.cpp whisper.cpp vllm podman omlmd huggingface
so if you like this tool, give some of these repos a ⭐, and hey, give us a ⭐ too while you are at it.
Open to contributors