| Name | llama-cpp-python JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | None |
| Summary | Python bindings for the llama.cpp library |
| upload_time | 2024-09-29 19:29:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<img src="https://raw.githubusercontent.com/abetlen/llama-cpp-python/main/docs/icon.svg" style="height: 5rem; width: 5rem">
</p>
# Python Bindings for [`llama.cpp`](https://github.com/ggerganov/llama.cpp)
[](https://llama-cpp-python.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/abetlen/llama-cpp-python/actions/workflows/test.yaml)
[](https://pypi.org/project/llama-cpp-python/)
[](https://pypi.org/project/llama-cpp-python/)
[](https://pypi.org/project/llama-cpp-python/)
[](https://pypi.org/project/llama-cpp-python/)
[]()
Simple Python bindings for **@ggerganov's** [`llama.cpp`](https://github.com/ggerganov/llama.cpp) library.
This package provides:
- Low-level access to C API via `ctypes` interface.
- High-level Python API for text completion
- OpenAI-like API
- [LangChain compatibility](https://python.langchain.com/docs/integrations/llms/llamacpp)
- [LlamaIndex compatibility](https://docs.llamaindex.ai/en/stable/examples/llm/llama_2_llama_cpp.html)
- OpenAI compatible web server
- [Local Copilot replacement](https://llama-cpp-python.readthedocs.io/en/latest/server/#code-completion)
- [Function Calling support](https://llama-cpp-python.readthedocs.io/en/latest/server/#function-calling)
- [Vision API support](https://llama-cpp-python.readthedocs.io/en/latest/server/#multimodal-models)
- [Multiple Models](https://llama-cpp-python.readthedocs.io/en/latest/server/#configuration-and-multi-model-support)
Documentation is available at [https://llama-cpp-python.readthedocs.io/en/latest](https://llama-cpp-python.readthedocs.io/en/latest).
## Installation
Requirements:
- Python 3.8+
- C compiler
- Linux: gcc or clang
- Windows: Visual Studio or MinGW
- MacOS: Xcode
To install the package, run:
```bash
pip install llama-cpp-python
```
This will also build `llama.cpp` from source and install it alongside this python package.
If this fails, add `--verbose` to the `pip install` see the full cmake build log.
**Pre-built Wheel (New)**
It is also possible to install a pre-built wheel with basic CPU support.
```bash
pip install llama-cpp-python \
--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
```
### Installation Configuration
`llama.cpp` supports a number of hardware acceleration backends to speed up inference as well as backend specific options. See the [llama.cpp README](https://github.com/ggerganov/llama.cpp#build) for a full list.
All `llama.cpp` cmake build options can be set via the `CMAKE_ARGS` environment variable or via the `--config-settings / -C` cli flag during installation.
<details open>
<summary>Environment Variables</summary>
```bash
# Linux and Mac
CMAKE_ARGS="-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS" \
pip install llama-cpp-python
```
```powershell
# Windows
$env:CMAKE_ARGS = "-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS"
pip install llama-cpp-python
```
</details>
<details>
<summary>CLI / requirements.txt</summary>
They can also be set via `pip install -C / --config-settings` command and saved to a `requirements.txt` file:
```bash
pip install --upgrade pip # ensure pip is up to date
pip install llama-cpp-python \
-C cmake.args="-DGGML_BLAS=ON;-DGGML_BLAS_VENDOR=OpenBLAS"
```
```txt
# requirements.txt
llama-cpp-python -C cmake.args="-DGGML_BLAS=ON;-DGGML_BLAS_VENDOR=OpenBLAS"
```
</details>
### Supported Backends
Below are some common backends, their build commands and any additional environment variables required.
<details open>
<summary>OpenBLAS (CPU)</summary>
To install with OpenBLAS, set the `GGML_BLAS` and `GGML_BLAS_VENDOR` environment variables before installing:
```bash
CMAKE_ARGS="-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS" pip install llama-cpp-python
```
</details>
<details>
<summary>CUDA</summary>
To install with CUDA support, set the `GGML_CUDA=on` environment variable before installing:
```bash
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python
```
**Pre-built Wheel (New)**
It is also possible to install a pre-built wheel with CUDA support. As long as your system meets some requirements:
- CUDA Version is 12.1, 12.2, 12.3, 12.4 or 12.5
- Python Version is 3.10, 3.11 or 3.12
```bash
pip install llama-cpp-python \
--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/<cuda-version>
```
Where `<cuda-version>` is one of the following:
- `cu121`: CUDA 12.1
- `cu122`: CUDA 12.2
- `cu123`: CUDA 12.3
- `cu124`: CUDA 12.4
- `cu125`: CUDA 12.5
For example, to install the CUDA 12.1 wheel:
```bash
pip install llama-cpp-python \
--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121
```
</details>
<details>
<summary>Metal</summary>
To install with Metal (MPS), set the `GGML_METAL=on` environment variable before installing:
```bash
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python
```
**Pre-built Wheel (New)**
It is also possible to install a pre-built wheel with Metal support. As long as your system meets some requirements:
- MacOS Version is 11.0 or later
- Python Version is 3.10, 3.11 or 3.12
```bash
pip install llama-cpp-python \
--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/metal
```
</details>
<details>
<summary>hipBLAS (ROCm)</summary>
To install with hipBLAS / ROCm support for AMD cards, set the `GGML_HIPBLAS=on` environment variable before installing:
```bash
CMAKE_ARGS="-DGGML_HIPBLAS=on" pip install llama-cpp-python
```
</details>
<details>
<summary>Vulkan</summary>
To install with Vulkan support, set the `GGML_VULKAN=on` environment variable before installing:
```bash
CMAKE_ARGS="-DGGML_VULKAN=on" pip install llama-cpp-python
```
</details>
<details>
<summary>SYCL</summary>
To install with SYCL support, set the `GGML_SYCL=on` environment variable before installing:
```bash
source /opt/intel/oneapi/setvars.sh
CMAKE_ARGS="-DGGML_SYCL=on -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx" pip install llama-cpp-python
```
</details>
<details>
<summary>RPC</summary>
To install with RPC support, set the `GGML_RPC=on` environment variable before installing:
```bash
source /opt/intel/oneapi/setvars.sh
CMAKE_ARGS="-DGGML_RPC=on" pip install llama-cpp-python
```
</details>
### Windows Notes
<details>
<summary>Error: Can't find 'nmake' or 'CMAKE_C_COMPILER'</summary>
If you run into issues where it complains it can't find `'nmake'` `'?'` or CMAKE_C_COMPILER, you can extract w64devkit as [mentioned in llama.cpp repo](https://github.com/ggerganov/llama.cpp#openblas) and add those manually to CMAKE_ARGS before running `pip` install:
```ps
$env:CMAKE_GENERATOR = "MinGW Makefiles"
$env:CMAKE_ARGS = "-DGGML_OPENBLAS=on -DCMAKE_C_COMPILER=C:/w64devkit/bin/gcc.exe -DCMAKE_CXX_COMPILER=C:/w64devkit/bin/g++.exe"
```
See the above instructions and set `CMAKE_ARGS` to the BLAS backend you want to use.
</details>
### MacOS Notes
Detailed MacOS Metal GPU install documentation is available at [docs/install/macos.md](https://llama-cpp-python.readthedocs.io/en/latest/install/macos/)
<details>
<summary>M1 Mac Performance Issue</summary>
Note: If you are using Apple Silicon (M1) Mac, make sure you have installed a version of Python that supports arm64 architecture. For example:
```bash
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh
bash Miniforge3-MacOSX-arm64.sh
```
Otherwise, while installing it will build the llama.cpp x86 version which will be 10x slower on Apple Silicon (M1) Mac.
</details>
<details>
<summary>M Series Mac Error: `(mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64'))`</summary>
Try installing with
```bash
CMAKE_ARGS="-DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_APPLE_SILICON_PROCESSOR=arm64 -DGGML_METAL=on" pip install --upgrade --verbose --force-reinstall --no-cache-dir llama-cpp-python
```
</details>
### Upgrading and Reinstalling
To upgrade and rebuild `llama-cpp-python` add `--upgrade --force-reinstall --no-cache-dir` flags to the `pip install` command to ensure the package is rebuilt from source.
## High-level API
[API Reference](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#high-level-api)
The high-level API provides a simple managed interface through the [`Llama`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama) class.
Below is a short example demonstrating how to use the high-level API to for basic text completion:
```python
from llama_cpp import Llama
llm = Llama(
model_path="./models/7B/llama-model.gguf",
# n_gpu_layers=-1, # Uncomment to use GPU acceleration
# seed=1337, # Uncomment to set a specific seed
# n_ctx=2048, # Uncomment to increase the context window
)
output = llm(
"Q: Name the planets in the solar system? A: ", # Prompt
max_tokens=32, # Generate up to 32 tokens, set to None to generate up to the end of the context window
stop=["Q:", "\n"], # Stop generating just before the model would generate a new question
echo=True # Echo the prompt back in the output
) # Generate a completion, can also call create_completion
print(output)
```
By default `llama-cpp-python` generates completions in an OpenAI compatible format:
```python
{
"id": "cmpl-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"object": "text_completion",
"created": 1679561337,
"model": "./models/7B/llama-model.gguf",
"choices": [
{
"text": "Q: Name the planets in the solar system? A: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune and Pluto.",
"index": 0,
"logprobs": None,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 14,
"completion_tokens": 28,
"total_tokens": 42
}
}
```
Text completion is available through the [`__call__`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.__call__) and [`create_completion`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_completion) methods of the [`Llama`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama) class.
### Pulling models from Hugging Face Hub
You can download `Llama` models in `gguf` format directly from Hugging Face using the [`from_pretrained`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.from_pretrained) method.
You'll need to install the `huggingface-hub` package to use this feature (`pip install huggingface-hub`).
```python
llm = Llama.from_pretrained(
repo_id="Qwen/Qwen2-0.5B-Instruct-GGUF",
filename="*q8_0.gguf",
verbose=False
)
```
By default [`from_pretrained`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.from_pretrained) will download the model to the huggingface cache directory, you can then manage installed model files with the [`huggingface-cli`](https://huggingface.co/docs/huggingface_hub/en/guides/cli) tool.
### Chat Completion
The high-level API also provides a simple interface for chat completion.
Chat completion requires that the model knows how to format the messages into a single prompt.
The `Llama` class does this using pre-registered chat formats (ie. `chatml`, `llama-2`, `gemma`, etc) or by providing a custom chat handler object.
The model will will format the messages into a single prompt using the following order of precedence:
- Use the `chat_handler` if provided
- Use the `chat_format` if provided
- Use the `tokenizer.chat_template` from the `gguf` model's metadata (should work for most new models, older models may not have this)
- else, fallback to the `llama-2` chat format
Set `verbose=True` to see the selected chat format.
```python
from llama_cpp import Llama
llm = Llama(
model_path="path/to/llama-2/llama-model.gguf",
chat_format="llama-2"
)
llm.create_chat_completion(
messages = [
{"role": "system", "content": "You are an assistant who perfectly describes images."},
{
"role": "user",
"content": "Describe this image in detail please."
}
]
)
```
Chat completion is available through the [`create_chat_completion`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion) method of the [`Llama`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama) class.
For OpenAI API v1 compatibility, you use the [`create_chat_completion_openai_v1`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion_openai_v1) method which will return pydantic models instead of dicts.
### JSON and JSON Schema Mode
To constrain chat responses to only valid JSON or a specific JSON Schema use the `response_format` argument in [`create_chat_completion`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion).
#### JSON Mode
The following example will constrain the response to valid JSON strings only.
```python
from llama_cpp import Llama
llm = Llama(model_path="path/to/model.gguf", chat_format="chatml")
llm.create_chat_completion(
messages=[
{
"role": "system",
"content": "You are a helpful assistant that outputs in JSON.",
},
{"role": "user", "content": "Who won the world series in 2020"},
],
response_format={
"type": "json_object",
},
temperature=0.7,
)
```
#### JSON Schema Mode
To constrain the response further to a specific JSON Schema add the schema to the `schema` property of the `response_format` argument.
```python
from llama_cpp import Llama
llm = Llama(model_path="path/to/model.gguf", chat_format="chatml")
llm.create_chat_completion(
messages=[
{
"role": "system",
"content": "You are a helpful assistant that outputs in JSON.",
},
{"role": "user", "content": "Who won the world series in 2020"},
],
response_format={
"type": "json_object",
"schema": {
"type": "object",
"properties": {"team_name": {"type": "string"}},
"required": ["team_name"],
},
},
temperature=0.7,
)
```
### Function Calling
The high-level API supports OpenAI compatible function and tool calling. This is possible through the `functionary` pre-trained models chat format or through the generic `chatml-function-calling` chat format.
```python
from llama_cpp import Llama
llm = Llama(model_path="path/to/chatml/llama-model.gguf", chat_format="chatml-function-calling")
llm.create_chat_completion(
messages = [
{
"role": "system",
"content": "A chat between a curious user and an artificial intelligence assistant. The assistant gives helpful, detailed, and polite answers to the user's questions. The assistant calls functions with appropriate input when necessary"
},
{
"role": "user",
"content": "Extract Jason is 25 years old"
}
],
tools=[{
"type": "function",
"function": {
"name": "UserDetail",
"parameters": {
"type": "object",
"title": "UserDetail",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"age": {
"title": "Age",
"type": "integer"
}
},
"required": [ "name", "age" ]
}
}
}],
tool_choice={
"type": "function",
"function": {
"name": "UserDetail"
}
}
)
```
<details>
<summary>Functionary v2</summary>
The various gguf-converted files for this set of models can be found [here](https://huggingface.co/meetkai). Functionary is able to intelligently call functions and also analyze any provided function outputs to generate coherent responses. All v2 models of functionary supports **parallel function calling**. You can provide either `functionary-v1` or `functionary-v2` for the `chat_format` when initializing the Llama class.
Due to discrepancies between llama.cpp and HuggingFace's tokenizers, it is required to provide HF Tokenizer for functionary. The `LlamaHFTokenizer` class can be initialized and passed into the Llama class. This will override the default llama.cpp tokenizer used in Llama class. The tokenizer files are already included in the respective HF repositories hosting the gguf files.
```python
from llama_cpp import Llama
from llama_cpp.llama_tokenizer import LlamaHFTokenizer
llm = Llama.from_pretrained(
repo_id="meetkai/functionary-small-v2.2-GGUF",
filename="functionary-small-v2.2.q4_0.gguf",
chat_format="functionary-v2",
tokenizer=LlamaHFTokenizer.from_pretrained("meetkai/functionary-small-v2.2-GGUF")
)
```
**NOTE**: There is no need to provide the default system messages used in Functionary as they are added automatically in the Functionary chat handler. Thus, the messages should contain just the chat messages and/or system messages that provide additional context for the model (e.g.: datetime, etc.).
</details>
### Multi-modal Models
`llama-cpp-python` supports such as llava1.5 which allow the language model to read information from both text and images.
Below are the supported multi-modal models and their respective chat handlers (Python API) and chat formats (Server API).
| Model | `LlamaChatHandler` | `chat_format` |
|:--- |:--- |:--- |
| [llava-v1.5-7b](https://huggingface.co/mys/ggml_llava-v1.5-7b) | `Llava15ChatHandler` | `llava-1-5` |
| [llava-v1.5-13b](https://huggingface.co/mys/ggml_llava-v1.5-13b) | `Llava15ChatHandler` | `llava-1-5` |
| [llava-v1.6-34b](https://huggingface.co/cjpais/llava-v1.6-34B-gguf) | `Llava16ChatHandler` | `llava-1-6` |
| [moondream2](https://huggingface.co/vikhyatk/moondream2) | `MoondreamChatHandler` | `moondream2` |
| [nanollava](https://huggingface.co/abetlen/nanollava-gguf) | `NanollavaChatHandler` | `nanollava` |
| [llama-3-vision-alpha](https://huggingface.co/abetlen/llama-3-vision-alpha-gguf) | `Llama3VisionAlphaChatHandler` | `llama-3-vision-alpha` |
| [minicpm-v-2.6](https://huggingface.co/openbmb/MiniCPM-V-2_6-gguf) | `MiniCPMv26ChatHandler` | `minicpm-v-2.6` |
Then you'll need to use a custom chat handler to load the clip model and process the chat messages and images.
```python
from llama_cpp import Llama
from llama_cpp.llama_chat_format import Llava15ChatHandler
chat_handler = Llava15ChatHandler(clip_model_path="path/to/llava/mmproj.bin")
llm = Llama(
model_path="./path/to/llava/llama-model.gguf",
chat_handler=chat_handler,
n_ctx=2048, # n_ctx should be increased to accommodate the image embedding
)
llm.create_chat_completion(
messages = [
{"role": "system", "content": "You are an assistant who perfectly describes images."},
{
"role": "user",
"content": [
{"type" : "text", "text": "What's in this image?"},
{"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" } }
]
}
]
)
```
You can also pull the model from the Hugging Face Hub using the `from_pretrained` method.
```python
from llama_cpp import Llama
from llama_cpp.llama_chat_format import MoondreamChatHandler
chat_handler = MoondreamChatHandler.from_pretrained(
repo_id="vikhyatk/moondream2",
filename="*mmproj*",
)
llm = Llama.from_pretrained(
repo_id="vikhyatk/moondream2",
filename="*text-model*",
chat_handler=chat_handler,
n_ctx=2048, # n_ctx should be increased to accommodate the image embedding
)
response = llm.create_chat_completion(
messages = [
{
"role": "user",
"content": [
{"type" : "text", "text": "What's in this image?"},
{"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" } }
]
}
]
)
print(response["choices"][0]["text"])
```
**Note**: Multi-modal models also support tool calling and JSON mode.
<details>
<summary>Loading a Local Image</summary>
Images can be passed as base64 encoded data URIs. The following example demonstrates how to do this.
```python
import base64
def image_to_base64_data_uri(file_path):
with open(file_path, "rb") as img_file:
base64_data = base64.b64encode(img_file.read()).decode('utf-8')
return f"data:image/png;base64,{base64_data}"
# Replace 'file_path.png' with the actual path to your PNG file
file_path = 'file_path.png'
data_uri = image_to_base64_data_uri(file_path)
messages = [
{"role": "system", "content": "You are an assistant who perfectly describes images."},
{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": data_uri }},
{"type" : "text", "text": "Describe this image in detail please."}
]
}
]
```
</details>
### Speculative Decoding
`llama-cpp-python` supports speculative decoding which allows the model to generate completions based on a draft model.
The fastest way to use speculative decoding is through the `LlamaPromptLookupDecoding` class.
Just pass this as a draft model to the `Llama` class during initialization.
```python
from llama_cpp import Llama
from llama_cpp.llama_speculative import LlamaPromptLookupDecoding
llama = Llama(
model_path="path/to/model.gguf",
draft_model=LlamaPromptLookupDecoding(num_pred_tokens=10) # num_pred_tokens is the number of tokens to predict 10 is the default and generally good for gpu, 2 performs better for cpu-only machines.
)
```
### Embeddings
To generate text embeddings use [`create_embedding`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_embedding) or [`embed`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.embed). Note that you must pass `embedding=True` to the constructor upon model creation for these to work properly.
```python
import llama_cpp
llm = llama_cpp.Llama(model_path="path/to/model.gguf", embedding=True)
embeddings = llm.create_embedding("Hello, world!")
# or create multiple embeddings at once
embeddings = llm.create_embedding(["Hello, world!", "Goodbye, world!"])
```
There are two primary notions of embeddings in a Transformer-style model: *token level* and *sequence level*. Sequence level embeddings are produced by "pooling" token level embeddings together, usually by averaging them or using the first token.
Models that are explicitly geared towards embeddings will usually return sequence level embeddings by default, one for each input string. Non-embedding models such as those designed for text generation will typically return only token level embeddings, one for each token in each sequence. Thus the dimensionality of the return type will be one higher for token level embeddings.
It is possible to control pooling behavior in some cases using the `pooling_type` flag on model creation. You can ensure token level embeddings from any model using `LLAMA_POOLING_TYPE_NONE`. The reverse, getting a generation oriented model to yield sequence level embeddings is currently not possible, but you can always do the pooling manually.
### Adjusting the Context Window
The context window of the Llama models determines the maximum number of tokens that can be processed at once. By default, this is set to 512 tokens, but can be adjusted based on your requirements.
For instance, if you want to work with larger contexts, you can expand the context window by setting the n_ctx parameter when initializing the Llama object:
```python
llm = Llama(model_path="./models/7B/llama-model.gguf", n_ctx=2048)
```
## OpenAI Compatible Web Server
`llama-cpp-python` offers a web server which aims to act as a drop-in replacement for the OpenAI API.
This allows you to use llama.cpp compatible models with any OpenAI compatible client (language libraries, services, etc).
To install the server package and get started:
```bash
pip install 'llama-cpp-python[server]'
python3 -m llama_cpp.server --model models/7B/llama-model.gguf
```
Similar to Hardware Acceleration section above, you can also install with GPU (cuBLAS) support like this:
```bash
CMAKE_ARGS="-DGGML_CUDA=on" FORCE_CMAKE=1 pip install 'llama-cpp-python[server]'
python3 -m llama_cpp.server --model models/7B/llama-model.gguf --n_gpu_layers 35
```
Navigate to [http://localhost:8000/docs](http://localhost:8000/docs) to see the OpenAPI documentation.
To bind to `0.0.0.0` to enable remote connections, use `python3 -m llama_cpp.server --host 0.0.0.0`.
Similarly, to change the port (default is 8000), use `--port`.
You probably also want to set the prompt format. For chatml, use
```bash
python3 -m llama_cpp.server --model models/7B/llama-model.gguf --chat_format chatml
```
That will format the prompt according to how model expects it. You can find the prompt format in the model card.
For possible options, see [llama_cpp/llama_chat_format.py](llama_cpp/llama_chat_format.py) and look for lines starting with "@register_chat_format".
If you have `huggingface-hub` installed, you can also use the `--hf_model_repo_id` flag to load a model from the Hugging Face Hub.
```bash
python3 -m llama_cpp.server --hf_model_repo_id Qwen/Qwen2-0.5B-Instruct-GGUF --model '*q8_0.gguf'
```
### Web Server Features
- [Local Copilot replacement](https://llama-cpp-python.readthedocs.io/en/latest/server/#code-completion)
- [Function Calling support](https://llama-cpp-python.readthedocs.io/en/latest/server/#function-calling)
- [Vision API support](https://llama-cpp-python.readthedocs.io/en/latest/server/#multimodal-models)
- [Multiple Models](https://llama-cpp-python.readthedocs.io/en/latest/server/#configuration-and-multi-model-support)
## Docker image
A Docker image is available on [GHCR](https://ghcr.io/abetlen/llama-cpp-python). To run the server:
```bash
docker run --rm -it -p 8000:8000 -v /path/to/models:/models -e MODEL=/models/llama-model.gguf ghcr.io/abetlen/llama-cpp-python:latest
```
[Docker on termux (requires root)](https://gist.github.com/FreddieOliveira/efe850df7ff3951cb62d74bd770dce27) is currently the only known way to run this on phones, see [termux support issue](https://github.com/abetlen/llama-cpp-python/issues/389)
## Low-level API
[API Reference](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#low-level-api)
The low-level API is a direct [`ctypes`](https://docs.python.org/3/library/ctypes.html) binding to the C API provided by `llama.cpp`.
The entire low-level API can be found in [llama_cpp/llama_cpp.py](https://github.com/abetlen/llama-cpp-python/blob/master/llama_cpp/llama_cpp.py) and directly mirrors the C API in [llama.h](https://github.com/ggerganov/llama.cpp/blob/master/llama.h).
Below is a short example demonstrating how to use the low-level API to tokenize a prompt:
```python
import llama_cpp
import ctypes
llama_cpp.llama_backend_init(False) # Must be called once at the start of each program
params = llama_cpp.llama_context_default_params()
# use bytes for char * params
model = llama_cpp.llama_load_model_from_file(b"./models/7b/llama-model.gguf", params)
ctx = llama_cpp.llama_new_context_with_model(model, params)
max_tokens = params.n_ctx
# use ctypes arrays for array params
tokens = (llama_cpp.llama_token * int(max_tokens))()
n_tokens = llama_cpp.llama_tokenize(ctx, b"Q: Name the planets in the solar system? A: ", tokens, max_tokens, llama_cpp.c_bool(True))
llama_cpp.llama_free(ctx)
```
Check out the [examples folder](examples/low_level_api) for more examples of using the low-level API.
## Documentation
Documentation is available via [https://llama-cpp-python.readthedocs.io/](https://llama-cpp-python.readthedocs.io/).
If you find any issues with the documentation, please open an issue or submit a PR.
## Development
This package is under active development and I welcome any contributions.
To get started, clone the repository and install the package in editable / development mode:
```bash
git clone --recurse-submodules https://github.com/abetlen/llama-cpp-python.git
cd llama-cpp-python
# Upgrade pip (required for editable mode)
pip install --upgrade pip
# Install with pip
pip install -e .
# if you want to use the fastapi / openapi server
pip install -e .[server]
# to install all optional dependencies
pip install -e .[all]
# to clear the local build cache
make clean
```
You can also test out specific commits of `llama.cpp` by checking out the desired commit in the `vendor/llama.cpp` submodule and then running `make clean` and `pip install -e .` again. Any changes in the `llama.h` API will require
changes to the `llama_cpp/llama_cpp.py` file to match the new API (additional changes may be required elsewhere).
## FAQ
### Are there pre-built binaries / binary wheels available?
The recommended installation method is to install from source as described above.
The reason for this is that `llama.cpp` is built with compiler optimizations that are specific to your system.
Using pre-built binaries would require disabling these optimizations or supporting a large number of pre-built binaries for each platform.
That being said there are some pre-built binaries available through the Releases as well as some community provided wheels.
In the future, I would like to provide pre-built binaries and wheels for common platforms and I'm happy to accept any useful contributions in this area.
This is currently being tracked in [#741](https://github.com/abetlen/llama-cpp-python/issues/741)
### How does this compare to other Python bindings of `llama.cpp`?
I originally wrote this package for my own use with two goals in mind:
- Provide a simple process to install `llama.cpp` and access the full C API in `llama.h` from Python
- Provide a high-level Python API that can be used as a drop-in replacement for the OpenAI API so existing apps can be easily ported to use `llama.cpp`
Any contributions and changes to this package will be made with these goals in mind.
## License
This project is licensed under the terms of the MIT license.
Raw data
{
"_id": null,
"home_page": null,
"name": "llama-cpp-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Andrei Betlen <abetlen@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b5/14/85052d76d7f92ed97de7a7bc54f6b6cc04c2c25f6d8775cfe37d976e1842/llama_cpp_python-0.3.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/abetlen/llama-cpp-python/main/docs/icon.svg\" style=\"height: 5rem; width: 5rem\">\n</p>\n\n# Python Bindings for [`llama.cpp`](https://github.com/ggerganov/llama.cpp)\n\n[](https://llama-cpp-python.readthedocs.io/en/latest/?badge=latest)\n[](https://github.com/abetlen/llama-cpp-python/actions/workflows/test.yaml)\n[](https://pypi.org/project/llama-cpp-python/)\n[](https://pypi.org/project/llama-cpp-python/)\n[](https://pypi.org/project/llama-cpp-python/)\n[](https://pypi.org/project/llama-cpp-python/)\n[]()\n\nSimple Python bindings for **@ggerganov's** [`llama.cpp`](https://github.com/ggerganov/llama.cpp) library.\nThis package provides:\n\n- Low-level access to C API via `ctypes` interface.\n- High-level Python API for text completion\n - OpenAI-like API\n - [LangChain compatibility](https://python.langchain.com/docs/integrations/llms/llamacpp)\n - [LlamaIndex compatibility](https://docs.llamaindex.ai/en/stable/examples/llm/llama_2_llama_cpp.html)\n- OpenAI compatible web server\n - [Local Copilot replacement](https://llama-cpp-python.readthedocs.io/en/latest/server/#code-completion)\n - [Function Calling support](https://llama-cpp-python.readthedocs.io/en/latest/server/#function-calling)\n - [Vision API support](https://llama-cpp-python.readthedocs.io/en/latest/server/#multimodal-models)\n - [Multiple Models](https://llama-cpp-python.readthedocs.io/en/latest/server/#configuration-and-multi-model-support)\n\nDocumentation is available at [https://llama-cpp-python.readthedocs.io/en/latest](https://llama-cpp-python.readthedocs.io/en/latest).\n\n## Installation\n\nRequirements:\n\n - Python 3.8+\n - C compiler\n - Linux: gcc or clang\n - Windows: Visual Studio or MinGW\n - MacOS: Xcode\n\nTo install the package, run:\n\n```bash\npip install llama-cpp-python\n```\n\nThis will also build `llama.cpp` from source and install it alongside this python package.\n\nIf this fails, add `--verbose` to the `pip install` see the full cmake build log.\n\n**Pre-built Wheel (New)**\n\nIt is also possible to install a pre-built wheel with basic CPU support.\n\n```bash\npip install llama-cpp-python \\\n --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu\n```\n\n### Installation Configuration\n\n`llama.cpp` supports a number of hardware acceleration backends to speed up inference as well as backend specific options. See the [llama.cpp README](https://github.com/ggerganov/llama.cpp#build) for a full list.\n\nAll `llama.cpp` cmake build options can be set via the `CMAKE_ARGS` environment variable or via the `--config-settings / -C` cli flag during installation.\n\n<details open>\n<summary>Environment Variables</summary>\n\n```bash\n# Linux and Mac\nCMAKE_ARGS=\"-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS\" \\\n pip install llama-cpp-python\n```\n\n```powershell\n# Windows\n$env:CMAKE_ARGS = \"-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS\"\npip install llama-cpp-python\n```\n</details>\n\n<details>\n<summary>CLI / requirements.txt</summary>\n\nThey can also be set via `pip install -C / --config-settings` command and saved to a `requirements.txt` file:\n\n```bash\npip install --upgrade pip # ensure pip is up to date\npip install llama-cpp-python \\\n -C cmake.args=\"-DGGML_BLAS=ON;-DGGML_BLAS_VENDOR=OpenBLAS\"\n```\n\n```txt\n# requirements.txt\n\nllama-cpp-python -C cmake.args=\"-DGGML_BLAS=ON;-DGGML_BLAS_VENDOR=OpenBLAS\"\n```\n\n</details>\n\n### Supported Backends\n\nBelow are some common backends, their build commands and any additional environment variables required.\n\n<details open>\n<summary>OpenBLAS (CPU)</summary>\n\nTo install with OpenBLAS, set the `GGML_BLAS` and `GGML_BLAS_VENDOR` environment variables before installing:\n\n```bash\nCMAKE_ARGS=\"-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS\" pip install llama-cpp-python\n```\n</details>\n\n<details>\n<summary>CUDA</summary>\n\nTo install with CUDA support, set the `GGML_CUDA=on` environment variable before installing:\n\n```bash\nCMAKE_ARGS=\"-DGGML_CUDA=on\" pip install llama-cpp-python\n```\n\n**Pre-built Wheel (New)**\n\nIt is also possible to install a pre-built wheel with CUDA support. As long as your system meets some requirements:\n\n- CUDA Version is 12.1, 12.2, 12.3, 12.4 or 12.5\n- Python Version is 3.10, 3.11 or 3.12\n\n```bash\npip install llama-cpp-python \\\n --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/<cuda-version>\n```\n\nWhere `<cuda-version>` is one of the following:\n- `cu121`: CUDA 12.1\n- `cu122`: CUDA 12.2\n- `cu123`: CUDA 12.3\n- `cu124`: CUDA 12.4\n- `cu125`: CUDA 12.5\n\nFor example, to install the CUDA 12.1 wheel:\n\n```bash\npip install llama-cpp-python \\\n --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121\n```\n\n</details>\n\n<details>\n<summary>Metal</summary>\n\nTo install with Metal (MPS), set the `GGML_METAL=on` environment variable before installing:\n\n```bash\nCMAKE_ARGS=\"-DGGML_METAL=on\" pip install llama-cpp-python\n```\n\n**Pre-built Wheel (New)**\n\nIt is also possible to install a pre-built wheel with Metal support. As long as your system meets some requirements:\n\n- MacOS Version is 11.0 or later\n- Python Version is 3.10, 3.11 or 3.12\n\n```bash\npip install llama-cpp-python \\\n --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/metal\n```\n\n</details>\n\n<details>\n<summary>hipBLAS (ROCm)</summary>\n\nTo install with hipBLAS / ROCm support for AMD cards, set the `GGML_HIPBLAS=on` environment variable before installing:\n\n```bash\nCMAKE_ARGS=\"-DGGML_HIPBLAS=on\" pip install llama-cpp-python\n```\n\n</details>\n\n<details>\n<summary>Vulkan</summary>\n\nTo install with Vulkan support, set the `GGML_VULKAN=on` environment variable before installing:\n\n```bash\nCMAKE_ARGS=\"-DGGML_VULKAN=on\" pip install llama-cpp-python\n```\n\n</details>\n\n<details>\n<summary>SYCL</summary>\n\nTo install with SYCL support, set the `GGML_SYCL=on` environment variable before installing:\n\n```bash\nsource /opt/intel/oneapi/setvars.sh \nCMAKE_ARGS=\"-DGGML_SYCL=on -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx\" pip install llama-cpp-python\n```\n</details>\n\n<details>\n<summary>RPC</summary>\n\nTo install with RPC support, set the `GGML_RPC=on` environment variable before installing:\n\n```bash\nsource /opt/intel/oneapi/setvars.sh \nCMAKE_ARGS=\"-DGGML_RPC=on\" pip install llama-cpp-python\n```\n</details>\n\n\n### Windows Notes\n\n<details>\n<summary>Error: Can't find 'nmake' or 'CMAKE_C_COMPILER'</summary>\n\nIf you run into issues where it complains it can't find `'nmake'` `'?'` or CMAKE_C_COMPILER, you can extract w64devkit as [mentioned in llama.cpp repo](https://github.com/ggerganov/llama.cpp#openblas) and add those manually to CMAKE_ARGS before running `pip` install:\n\n```ps\n$env:CMAKE_GENERATOR = \"MinGW Makefiles\"\n$env:CMAKE_ARGS = \"-DGGML_OPENBLAS=on -DCMAKE_C_COMPILER=C:/w64devkit/bin/gcc.exe -DCMAKE_CXX_COMPILER=C:/w64devkit/bin/g++.exe\"\n```\n\nSee the above instructions and set `CMAKE_ARGS` to the BLAS backend you want to use.\n</details>\n\n### MacOS Notes\n\nDetailed MacOS Metal GPU install documentation is available at [docs/install/macos.md](https://llama-cpp-python.readthedocs.io/en/latest/install/macos/)\n\n<details>\n<summary>M1 Mac Performance Issue</summary>\n\nNote: If you are using Apple Silicon (M1) Mac, make sure you have installed a version of Python that supports arm64 architecture. For example:\n\n```bash\nwget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh\nbash Miniforge3-MacOSX-arm64.sh\n```\n\nOtherwise, while installing it will build the llama.cpp x86 version which will be 10x slower on Apple Silicon (M1) Mac.\n</details>\n\n<details>\n<summary>M Series Mac Error: `(mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64'))`</summary>\n\nTry installing with\n\n```bash\nCMAKE_ARGS=\"-DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_APPLE_SILICON_PROCESSOR=arm64 -DGGML_METAL=on\" pip install --upgrade --verbose --force-reinstall --no-cache-dir llama-cpp-python\n```\n</details>\n\n### Upgrading and Reinstalling\n\nTo upgrade and rebuild `llama-cpp-python` add `--upgrade --force-reinstall --no-cache-dir` flags to the `pip install` command to ensure the package is rebuilt from source.\n\n## High-level API\n\n[API Reference](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#high-level-api)\n\nThe high-level API provides a simple managed interface through the [`Llama`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama) class.\n\nBelow is a short example demonstrating how to use the high-level API to for basic text completion:\n\n```python\nfrom llama_cpp import Llama\n\nllm = Llama(\n model_path=\"./models/7B/llama-model.gguf\",\n # n_gpu_layers=-1, # Uncomment to use GPU acceleration\n # seed=1337, # Uncomment to set a specific seed\n # n_ctx=2048, # Uncomment to increase the context window\n)\noutput = llm(\n \"Q: Name the planets in the solar system? A: \", # Prompt\n max_tokens=32, # Generate up to 32 tokens, set to None to generate up to the end of the context window\n stop=[\"Q:\", \"\\n\"], # Stop generating just before the model would generate a new question\n echo=True # Echo the prompt back in the output\n) # Generate a completion, can also call create_completion\nprint(output)\n```\n\nBy default `llama-cpp-python` generates completions in an OpenAI compatible format:\n\n```python\n{\n \"id\": \"cmpl-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n \"object\": \"text_completion\",\n \"created\": 1679561337,\n \"model\": \"./models/7B/llama-model.gguf\",\n \"choices\": [\n {\n \"text\": \"Q: Name the planets in the solar system? A: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune and Pluto.\",\n \"index\": 0,\n \"logprobs\": None,\n \"finish_reason\": \"stop\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 14,\n \"completion_tokens\": 28,\n \"total_tokens\": 42\n }\n}\n```\n\nText completion is available through the [`__call__`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.__call__) and [`create_completion`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_completion) methods of the [`Llama`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama) class.\n\n### Pulling models from Hugging Face Hub\n\nYou can download `Llama` models in `gguf` format directly from Hugging Face using the [`from_pretrained`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.from_pretrained) method.\nYou'll need to install the `huggingface-hub` package to use this feature (`pip install huggingface-hub`).\n\n```python\nllm = Llama.from_pretrained(\n repo_id=\"Qwen/Qwen2-0.5B-Instruct-GGUF\",\n filename=\"*q8_0.gguf\",\n verbose=False\n)\n```\n\nBy default [`from_pretrained`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.from_pretrained) will download the model to the huggingface cache directory, you can then manage installed model files with the [`huggingface-cli`](https://huggingface.co/docs/huggingface_hub/en/guides/cli) tool.\n\n### Chat Completion\n\nThe high-level API also provides a simple interface for chat completion.\n\nChat completion requires that the model knows how to format the messages into a single prompt.\nThe `Llama` class does this using pre-registered chat formats (ie. `chatml`, `llama-2`, `gemma`, etc) or by providing a custom chat handler object.\n\nThe model will will format the messages into a single prompt using the following order of precedence:\n - Use the `chat_handler` if provided\n - Use the `chat_format` if provided\n - Use the `tokenizer.chat_template` from the `gguf` model's metadata (should work for most new models, older models may not have this)\n - else, fallback to the `llama-2` chat format\n\nSet `verbose=True` to see the selected chat format.\n\n```python\nfrom llama_cpp import Llama\nllm = Llama(\n model_path=\"path/to/llama-2/llama-model.gguf\",\n chat_format=\"llama-2\"\n)\nllm.create_chat_completion(\n messages = [\n {\"role\": \"system\", \"content\": \"You are an assistant who perfectly describes images.\"},\n {\n \"role\": \"user\",\n \"content\": \"Describe this image in detail please.\"\n }\n ]\n)\n```\n\nChat completion is available through the [`create_chat_completion`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion) method of the [`Llama`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama) class.\n\nFor OpenAI API v1 compatibility, you use the [`create_chat_completion_openai_v1`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion_openai_v1) method which will return pydantic models instead of dicts.\n\n\n### JSON and JSON Schema Mode\n\nTo constrain chat responses to only valid JSON or a specific JSON Schema use the `response_format` argument in [`create_chat_completion`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_chat_completion).\n\n#### JSON Mode\n\nThe following example will constrain the response to valid JSON strings only.\n\n```python\nfrom llama_cpp import Llama\nllm = Llama(model_path=\"path/to/model.gguf\", chat_format=\"chatml\")\nllm.create_chat_completion(\n messages=[\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful assistant that outputs in JSON.\",\n },\n {\"role\": \"user\", \"content\": \"Who won the world series in 2020\"},\n ],\n response_format={\n \"type\": \"json_object\",\n },\n temperature=0.7,\n)\n```\n\n#### JSON Schema Mode\n\nTo constrain the response further to a specific JSON Schema add the schema to the `schema` property of the `response_format` argument.\n\n```python\nfrom llama_cpp import Llama\nllm = Llama(model_path=\"path/to/model.gguf\", chat_format=\"chatml\")\nllm.create_chat_completion(\n messages=[\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful assistant that outputs in JSON.\",\n },\n {\"role\": \"user\", \"content\": \"Who won the world series in 2020\"},\n ],\n response_format={\n \"type\": \"json_object\",\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\"team_name\": {\"type\": \"string\"}},\n \"required\": [\"team_name\"],\n },\n },\n temperature=0.7,\n)\n```\n\n### Function Calling\n\nThe high-level API supports OpenAI compatible function and tool calling. This is possible through the `functionary` pre-trained models chat format or through the generic `chatml-function-calling` chat format.\n\n```python\nfrom llama_cpp import Llama\nllm = Llama(model_path=\"path/to/chatml/llama-model.gguf\", chat_format=\"chatml-function-calling\")\nllm.create_chat_completion(\n messages = [\n {\n \"role\": \"system\",\n \"content\": \"A chat between a curious user and an artificial intelligence assistant. The assistant gives helpful, detailed, and polite answers to the user's questions. The assistant calls functions with appropriate input when necessary\"\n\n },\n {\n \"role\": \"user\",\n \"content\": \"Extract Jason is 25 years old\"\n }\n ],\n tools=[{\n \"type\": \"function\",\n \"function\": {\n \"name\": \"UserDetail\",\n \"parameters\": {\n \"type\": \"object\",\n \"title\": \"UserDetail\",\n \"properties\": {\n \"name\": {\n \"title\": \"Name\",\n \"type\": \"string\"\n },\n \"age\": {\n \"title\": \"Age\",\n \"type\": \"integer\"\n }\n },\n \"required\": [ \"name\", \"age\" ]\n }\n }\n }],\n tool_choice={\n \"type\": \"function\",\n \"function\": {\n \"name\": \"UserDetail\"\n }\n }\n)\n```\n\n<details>\n<summary>Functionary v2</summary>\n\nThe various gguf-converted files for this set of models can be found [here](https://huggingface.co/meetkai). Functionary is able to intelligently call functions and also analyze any provided function outputs to generate coherent responses. All v2 models of functionary supports **parallel function calling**. You can provide either `functionary-v1` or `functionary-v2` for the `chat_format` when initializing the Llama class.\n\nDue to discrepancies between llama.cpp and HuggingFace's tokenizers, it is required to provide HF Tokenizer for functionary. The `LlamaHFTokenizer` class can be initialized and passed into the Llama class. This will override the default llama.cpp tokenizer used in Llama class. The tokenizer files are already included in the respective HF repositories hosting the gguf files.\n\n```python\nfrom llama_cpp import Llama\nfrom llama_cpp.llama_tokenizer import LlamaHFTokenizer\nllm = Llama.from_pretrained(\n repo_id=\"meetkai/functionary-small-v2.2-GGUF\",\n filename=\"functionary-small-v2.2.q4_0.gguf\",\n chat_format=\"functionary-v2\",\n tokenizer=LlamaHFTokenizer.from_pretrained(\"meetkai/functionary-small-v2.2-GGUF\")\n)\n```\n\n**NOTE**: There is no need to provide the default system messages used in Functionary as they are added automatically in the Functionary chat handler. Thus, the messages should contain just the chat messages and/or system messages that provide additional context for the model (e.g.: datetime, etc.).\n</details>\n\n### Multi-modal Models\n\n`llama-cpp-python` supports such as llava1.5 which allow the language model to read information from both text and images.\n\nBelow are the supported multi-modal models and their respective chat handlers (Python API) and chat formats (Server API).\n\n| Model | `LlamaChatHandler` | `chat_format` |\n|:--- |:--- |:--- |\n| [llava-v1.5-7b](https://huggingface.co/mys/ggml_llava-v1.5-7b) | `Llava15ChatHandler` | `llava-1-5` |\n| [llava-v1.5-13b](https://huggingface.co/mys/ggml_llava-v1.5-13b) | `Llava15ChatHandler` | `llava-1-5` |\n| [llava-v1.6-34b](https://huggingface.co/cjpais/llava-v1.6-34B-gguf) | `Llava16ChatHandler` | `llava-1-6` |\n| [moondream2](https://huggingface.co/vikhyatk/moondream2) | `MoondreamChatHandler` | `moondream2` |\n| [nanollava](https://huggingface.co/abetlen/nanollava-gguf) | `NanollavaChatHandler` | `nanollava` |\n| [llama-3-vision-alpha](https://huggingface.co/abetlen/llama-3-vision-alpha-gguf) | `Llama3VisionAlphaChatHandler` | `llama-3-vision-alpha` |\n| [minicpm-v-2.6](https://huggingface.co/openbmb/MiniCPM-V-2_6-gguf) | `MiniCPMv26ChatHandler` | `minicpm-v-2.6` |\n\nThen you'll need to use a custom chat handler to load the clip model and process the chat messages and images.\n\n```python\nfrom llama_cpp import Llama\nfrom llama_cpp.llama_chat_format import Llava15ChatHandler\nchat_handler = Llava15ChatHandler(clip_model_path=\"path/to/llava/mmproj.bin\")\nllm = Llama(\n model_path=\"./path/to/llava/llama-model.gguf\",\n chat_handler=chat_handler,\n n_ctx=2048, # n_ctx should be increased to accommodate the image embedding\n)\nllm.create_chat_completion(\n messages = [\n {\"role\": \"system\", \"content\": \"You are an assistant who perfectly describes images.\"},\n {\n \"role\": \"user\",\n \"content\": [\n {\"type\" : \"text\", \"text\": \"What's in this image?\"},\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\" } }\n ]\n }\n ]\n)\n```\n\nYou can also pull the model from the Hugging Face Hub using the `from_pretrained` method.\n\n```python\nfrom llama_cpp import Llama\nfrom llama_cpp.llama_chat_format import MoondreamChatHandler\n\nchat_handler = MoondreamChatHandler.from_pretrained(\n repo_id=\"vikhyatk/moondream2\",\n filename=\"*mmproj*\",\n)\n\nllm = Llama.from_pretrained(\n repo_id=\"vikhyatk/moondream2\",\n filename=\"*text-model*\",\n chat_handler=chat_handler,\n n_ctx=2048, # n_ctx should be increased to accommodate the image embedding\n)\n\nresponse = llm.create_chat_completion(\n messages = [\n {\n \"role\": \"user\",\n \"content\": [\n {\"type\" : \"text\", \"text\": \"What's in this image?\"},\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\" } }\n\n ]\n }\n ]\n)\nprint(response[\"choices\"][0][\"text\"])\n```\n\n**Note**: Multi-modal models also support tool calling and JSON mode.\n\n<details>\n<summary>Loading a Local Image</summary>\n\nImages can be passed as base64 encoded data URIs. The following example demonstrates how to do this.\n\n```python\nimport base64\n\ndef image_to_base64_data_uri(file_path):\n with open(file_path, \"rb\") as img_file:\n base64_data = base64.b64encode(img_file.read()).decode('utf-8')\n return f\"data:image/png;base64,{base64_data}\"\n\n# Replace 'file_path.png' with the actual path to your PNG file\nfile_path = 'file_path.png'\ndata_uri = image_to_base64_data_uri(file_path)\n\nmessages = [\n {\"role\": \"system\", \"content\": \"You are an assistant who perfectly describes images.\"},\n {\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"image_url\", \"image_url\": {\"url\": data_uri }},\n {\"type\" : \"text\", \"text\": \"Describe this image in detail please.\"}\n ]\n }\n]\n\n```\n\n</details>\n\n### Speculative Decoding\n\n`llama-cpp-python` supports speculative decoding which allows the model to generate completions based on a draft model.\n\nThe fastest way to use speculative decoding is through the `LlamaPromptLookupDecoding` class.\n\nJust pass this as a draft model to the `Llama` class during initialization.\n\n```python\nfrom llama_cpp import Llama\nfrom llama_cpp.llama_speculative import LlamaPromptLookupDecoding\n\nllama = Llama(\n model_path=\"path/to/model.gguf\",\n draft_model=LlamaPromptLookupDecoding(num_pred_tokens=10) # num_pred_tokens is the number of tokens to predict 10 is the default and generally good for gpu, 2 performs better for cpu-only machines.\n)\n```\n\n### Embeddings\n\nTo generate text embeddings use [`create_embedding`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.create_embedding) or [`embed`](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#llama_cpp.Llama.embed). Note that you must pass `embedding=True` to the constructor upon model creation for these to work properly.\n\n```python\nimport llama_cpp\n\nllm = llama_cpp.Llama(model_path=\"path/to/model.gguf\", embedding=True)\n\nembeddings = llm.create_embedding(\"Hello, world!\")\n\n# or create multiple embeddings at once\n\nembeddings = llm.create_embedding([\"Hello, world!\", \"Goodbye, world!\"])\n```\n\nThere are two primary notions of embeddings in a Transformer-style model: *token level* and *sequence level*. Sequence level embeddings are produced by \"pooling\" token level embeddings together, usually by averaging them or using the first token.\n\nModels that are explicitly geared towards embeddings will usually return sequence level embeddings by default, one for each input string. Non-embedding models such as those designed for text generation will typically return only token level embeddings, one for each token in each sequence. Thus the dimensionality of the return type will be one higher for token level embeddings.\n\nIt is possible to control pooling behavior in some cases using the `pooling_type` flag on model creation. You can ensure token level embeddings from any model using `LLAMA_POOLING_TYPE_NONE`. The reverse, getting a generation oriented model to yield sequence level embeddings is currently not possible, but you can always do the pooling manually.\n\n### Adjusting the Context Window\n\nThe context window of the Llama models determines the maximum number of tokens that can be processed at once. By default, this is set to 512 tokens, but can be adjusted based on your requirements.\n\nFor instance, if you want to work with larger contexts, you can expand the context window by setting the n_ctx parameter when initializing the Llama object:\n\n```python\nllm = Llama(model_path=\"./models/7B/llama-model.gguf\", n_ctx=2048)\n```\n\n## OpenAI Compatible Web Server\n\n`llama-cpp-python` offers a web server which aims to act as a drop-in replacement for the OpenAI API.\nThis allows you to use llama.cpp compatible models with any OpenAI compatible client (language libraries, services, etc).\n\nTo install the server package and get started:\n\n```bash\npip install 'llama-cpp-python[server]'\npython3 -m llama_cpp.server --model models/7B/llama-model.gguf\n```\n\nSimilar to Hardware Acceleration section above, you can also install with GPU (cuBLAS) support like this:\n\n```bash\nCMAKE_ARGS=\"-DGGML_CUDA=on\" FORCE_CMAKE=1 pip install 'llama-cpp-python[server]'\npython3 -m llama_cpp.server --model models/7B/llama-model.gguf --n_gpu_layers 35\n```\n\nNavigate to [http://localhost:8000/docs](http://localhost:8000/docs) to see the OpenAPI documentation.\n\nTo bind to `0.0.0.0` to enable remote connections, use `python3 -m llama_cpp.server --host 0.0.0.0`.\nSimilarly, to change the port (default is 8000), use `--port`.\n\nYou probably also want to set the prompt format. For chatml, use\n\n```bash\npython3 -m llama_cpp.server --model models/7B/llama-model.gguf --chat_format chatml\n```\n\nThat will format the prompt according to how model expects it. You can find the prompt format in the model card.\nFor possible options, see [llama_cpp/llama_chat_format.py](llama_cpp/llama_chat_format.py) and look for lines starting with \"@register_chat_format\".\n\nIf you have `huggingface-hub` installed, you can also use the `--hf_model_repo_id` flag to load a model from the Hugging Face Hub.\n\n```bash\npython3 -m llama_cpp.server --hf_model_repo_id Qwen/Qwen2-0.5B-Instruct-GGUF --model '*q8_0.gguf'\n```\n\n### Web Server Features\n\n- [Local Copilot replacement](https://llama-cpp-python.readthedocs.io/en/latest/server/#code-completion)\n- [Function Calling support](https://llama-cpp-python.readthedocs.io/en/latest/server/#function-calling)\n- [Vision API support](https://llama-cpp-python.readthedocs.io/en/latest/server/#multimodal-models)\n- [Multiple Models](https://llama-cpp-python.readthedocs.io/en/latest/server/#configuration-and-multi-model-support)\n\n## Docker image\n\nA Docker image is available on [GHCR](https://ghcr.io/abetlen/llama-cpp-python). To run the server:\n\n```bash\ndocker run --rm -it -p 8000:8000 -v /path/to/models:/models -e MODEL=/models/llama-model.gguf ghcr.io/abetlen/llama-cpp-python:latest\n```\n\n[Docker on termux (requires root)](https://gist.github.com/FreddieOliveira/efe850df7ff3951cb62d74bd770dce27) is currently the only known way to run this on phones, see [termux support issue](https://github.com/abetlen/llama-cpp-python/issues/389)\n\n## Low-level API\n\n[API Reference](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/#low-level-api)\n\nThe low-level API is a direct [`ctypes`](https://docs.python.org/3/library/ctypes.html) binding to the C API provided by `llama.cpp`.\nThe entire low-level API can be found in [llama_cpp/llama_cpp.py](https://github.com/abetlen/llama-cpp-python/blob/master/llama_cpp/llama_cpp.py) and directly mirrors the C API in [llama.h](https://github.com/ggerganov/llama.cpp/blob/master/llama.h).\n\nBelow is a short example demonstrating how to use the low-level API to tokenize a prompt:\n\n```python\nimport llama_cpp\nimport ctypes\nllama_cpp.llama_backend_init(False) # Must be called once at the start of each program\nparams = llama_cpp.llama_context_default_params()\n# use bytes for char * params\nmodel = llama_cpp.llama_load_model_from_file(b\"./models/7b/llama-model.gguf\", params)\nctx = llama_cpp.llama_new_context_with_model(model, params)\nmax_tokens = params.n_ctx\n# use ctypes arrays for array params\ntokens = (llama_cpp.llama_token * int(max_tokens))()\nn_tokens = llama_cpp.llama_tokenize(ctx, b\"Q: Name the planets in the solar system? A: \", tokens, max_tokens, llama_cpp.c_bool(True))\nllama_cpp.llama_free(ctx)\n```\n\nCheck out the [examples folder](examples/low_level_api) for more examples of using the low-level API.\n\n## Documentation\n\nDocumentation is available via [https://llama-cpp-python.readthedocs.io/](https://llama-cpp-python.readthedocs.io/).\nIf you find any issues with the documentation, please open an issue or submit a PR.\n\n## Development\n\nThis package is under active development and I welcome any contributions.\n\nTo get started, clone the repository and install the package in editable / development mode:\n\n```bash\ngit clone --recurse-submodules https://github.com/abetlen/llama-cpp-python.git\ncd llama-cpp-python\n\n# Upgrade pip (required for editable mode)\npip install --upgrade pip\n\n# Install with pip\npip install -e .\n\n# if you want to use the fastapi / openapi server\npip install -e .[server]\n\n# to install all optional dependencies\npip install -e .[all]\n\n# to clear the local build cache\nmake clean\n```\n\nYou can also test out specific commits of `llama.cpp` by checking out the desired commit in the `vendor/llama.cpp` submodule and then running `make clean` and `pip install -e .` again. Any changes in the `llama.h` API will require\nchanges to the `llama_cpp/llama_cpp.py` file to match the new API (additional changes may be required elsewhere).\n\n## FAQ\n\n### Are there pre-built binaries / binary wheels available?\n\nThe recommended installation method is to install from source as described above.\nThe reason for this is that `llama.cpp` is built with compiler optimizations that are specific to your system.\nUsing pre-built binaries would require disabling these optimizations or supporting a large number of pre-built binaries for each platform.\n\nThat being said there are some pre-built binaries available through the Releases as well as some community provided wheels.\n\nIn the future, I would like to provide pre-built binaries and wheels for common platforms and I'm happy to accept any useful contributions in this area.\nThis is currently being tracked in [#741](https://github.com/abetlen/llama-cpp-python/issues/741)\n\n### How does this compare to other Python bindings of `llama.cpp`?\n\nI originally wrote this package for my own use with two goals in mind:\n\n- Provide a simple process to install `llama.cpp` and access the full C API in `llama.h` from Python\n- Provide a high-level Python API that can be used as a drop-in replacement for the OpenAI API so existing apps can be easily ported to use `llama.cpp`\n\nAny contributions and changes to this package will be made with these goals in mind.\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python bindings for the llama.cpp library",
"version": "0.3.1",
"project_urls": {
"Changelog": "https://llama-cpp-python.readthedocs.io/en/latest/changelog/",
"Documentation": "https://llama-cpp-python.readthedocs.io/en/latest/",
"Homepage": "https://github.com/abetlen/llama-cpp-python",
"Issues": "https://github.com/abetlen/llama-cpp-python/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b51485052d76d7f92ed97de7a7bc54f6b6cc04c2c25f6d8775cfe37d976e1842",
"md5": "f4babd45b2d48808392138bf728b0426",
"sha256": "75ec8374960b6353c254e55a48e7c7783abf6bcb9178ba0f655490738e5a9004"
},
"downloads": -1,
"filename": "llama_cpp_python-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "f4babd45b2d48808392138bf728b0426",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 63903646,
"upload_time": "2024-09-29T19:29:30",
"upload_time_iso_8601": "2024-09-29T19:29:30.813093Z",
"url": "https://files.pythonhosted.org/packages/b5/14/85052d76d7f92ed97de7a7bc54f6b6cc04c2c25f6d8775cfe37d976e1842/llama_cpp_python-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-29 19:29:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abetlen",
"github_project": "llama-cpp-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "llama-cpp-python"
}
