Upload README.md

README.md

@@ -55,14 +55,16 @@ This repo contains GGUF format model files for [OpenOrca's Mixtral SlimOrca 8X7B
 
 GGUF is a new format introduced by the llama.cpp team on August 21st 2023. It is a replacement for GGML, which is no longer supported by llama.cpp.
 
-**MIXTRAL GGUF SUPPORT**
+### Mixtral GGUF
+
+Support for Mixtral was merged into Llama.cpp on December 13th.
+
+These Mixtral GGUFs are known to work in:
 
-Known to work in:
 * llama.cpp as of December 13th
 * KoboldCpp 1.52 as later
 * LM Studio 0.2.9 and later
-
-Support for Mixtral was merged into Llama.cpp on December 13th.
+* llama-cpp-python 0.2.23 and later
 
 Other clients/libraries, not listed above, may not yet work.
 
@@ -70,7 +72,6 @@ Other clients/libraries, not listed above, may not yet work.
 <!-- repositories-available start -->
 ## Repositories available
 
-* AWQ coming soon
 * [GPTQ models for GPU inference, with multiple quantisation parameter options.](https://huggingface.co/TheBloke/Mixtral-SlimOrca-8x7B-GPTQ)
 * [2, 3, 4, 5, 6 and 8-bit GGUF models for CPU+GPU inference](https://huggingface.co/TheBloke/Mixtral-SlimOrca-8x7B-GGUF)
 * [OpenOrca's original unquantised fp16 model in pytorch format, for GPU inference and for further conversions](https://huggingface.co/Open-Orca/Mixtral-SlimOrca-8x7B)
@@ -85,6 +86,7 @@ Other clients/libraries, not listed above, may not yet work.
 <|im_start|>user
 {prompt}<|im_end|>
 <|im_start|>assistant
+
 ```
 
 <!-- prompt-template end -->
@@ -93,9 +95,7 @@ Other clients/libraries, not listed above, may not yet work.
 <!-- compatibility_gguf start -->
 ## Compatibility
 
-These quantised GGUFv2 files are compatible with llama.cpp from December 13th onwards.
-
-They are also compatible with many third party UIs and libraries - please see the list at the top of this README.
+These Mixtral GGUFs are compatible with llama.cpp from December 13th onwards. Other clients/libraries may not work yet.
 
 ## Explanation of quantisation methods
 
@@ -198,12 +198,12 @@ Windows Command Line users: You can set the environment variable by running `set
 Make sure you are using `llama.cpp` from commit [d0cee0d](https://github.com/ggerganov/llama.cpp/commit/d0cee0d36d5be95a0d9088b674dbb27354107221) or later.
 
 ```shell
-./main -ngl 35 -m mixtral-slimorca-8x7b.Q4_K_M.gguf --color -c 32768 --temp 0.7 --repeat_penalty 1.1 -n -1 -p "<|im_start|>system\n{system_message}<|im_end|>\n<|im_start|>user\n{prompt}<|im_end|>\n<|im_start|>assistant"
+./main -ngl 35 -m mixtral-slimorca-8x7b.Q4_K_M.gguf --color -c 2048 --temp 0.7 --repeat_penalty 1.1 -n -1 -p "<|im_start|>system\n{system_message}<|im_end|>\n<|im_start|>user\n{prompt}<|im_end|>\n<|im_start|>assistant"
 ```
 
 Change `-ngl 32` to the number of layers to offload to GPU. Remove it if you don't have GPU acceleration.
 
-Change `-c 32768` to the desired sequence length. For extended sequence models - eg 8K, 16K, 32K - the necessary RoPE scaling parameters are read from the GGUF file and set by llama.cpp automatically. Note that longer sequence lengths require much more resources, so you may need to reduce this value.
+Change `-c 2048` to the desired sequence length. For extended sequence models - eg 8K, 16K, 32K - the necessary RoPE scaling parameters are read from the GGUF file and set by llama.cpp automatically. Note that longer sequence lengths require much more resources, so you may need to reduce this value.
 
 If you want to have a chat-style conversation, replace the `-p <PROMPT>` argument with `-i -ins`
 
@@ -211,16 +211,81 @@ For other parameters and how to use them, please refer to [the llama.cpp documen
 
 ## How to run in `text-generation-webui`
 
-Not yet supported
+Note that text-generation-webui may not yet be compatible with Mixtral GGUFs. Please check compatibility first.
+
+Further instructions can be found in the text-generation-webui documentation, here: [text-generation-webui/docs/04 ‐ Model Tab.md](https://github.com/oobabooga/text-generation-webui/blob/main/docs/04%20%E2%80%90%20Model%20Tab.md#llamacpp).
 
 ## How to run from Python code
 
-Not yet supported
+You can use GGUF models from Python using the [llama-cpp-python](https://github.com/abetlen/llama-cpp-python) version 0.2.23 and later.
 
 ### How to load this model in Python code, using llama-cpp-python
 
-Not yet supported
+For full documentation, please see: [llama-cpp-python docs](https://abetlen.github.io/llama-cpp-python/).
+
+#### First install the package
+
+Run one of the following commands, according to your system:
+
+```shell
+# Base ctransformers with no GPU acceleration
+pip install llama-cpp-python
+# With NVidia CUDA acceleration
+CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python
+# Or with OpenBLAS acceleration
+CMAKE_ARGS="-DLLAMA_BLAS=ON -DLLAMA_BLAS_VENDOR=OpenBLAS" pip install llama-cpp-python
+# Or with CLBLast acceleration
+CMAKE_ARGS="-DLLAMA_CLBLAST=on" pip install llama-cpp-python
+# Or with AMD ROCm GPU acceleration (Linux only)
+CMAKE_ARGS="-DLLAMA_HIPBLAS=on" pip install llama-cpp-python
+# Or with Metal GPU acceleration for macOS systems only
+CMAKE_ARGS="-DLLAMA_METAL=on" pip install llama-cpp-python
+
+# In windows, to set the variables CMAKE_ARGS in PowerShell, follow this format; eg for NVidia CUDA:
+$env:CMAKE_ARGS = "-DLLAMA_OPENBLAS=on"
+pip install llama-cpp-python
+```
+
+#### Simple llama-cpp-python example code
+
+```python
+from llama_cpp import Llama
+
+# Set gpu_layers to the number of layers to offload to GPU. Set to 0 if no GPU acceleration is available on your system.
+llm = Llama(
+  model_path="./mixtral-slimorca-8x7b.Q4_K_M.gguf",  # Download the model file first
+  n_ctx=2048,  # The max sequence length to use - note that longer sequence lengths require much more resources
+  n_threads=8,            # The number of CPU threads to use, tailor to your system and the resulting performance
+  n_gpu_layers=35         # The number of layers to offload to GPU, if you have GPU acceleration available
+)
+
+# Simple inference example
+output = llm(
+  "<|im_start|>system\n{system_message}<|im_end|>\n<|im_start|>user\n{prompt}<|im_end|>\n<|im_start|>assistant", # Prompt
+  max_tokens=512,  # Generate up to 512 tokens
+  stop=["</s>"],   # Example stop token - not necessarily correct for this specific model! Please check before using.
+  echo=True        # Whether to echo the prompt
+)
+
+# Chat Completion API
+
+llm = Llama(model_path="./mixtral-slimorca-8x7b.Q4_K_M.gguf", chat_format="llama-2")  # Set chat_format according to the model you are using
+llm.create_chat_completion(
+    messages = [
+        {"role": "system", "content": "You are a story writing assistant."},
+        {
+            "role": "user",
+            "content": "Write a story about llamas."
+        }
+    ]
+)
+```
+
+## How to use with LangChain
+
+Here are guides on using llama-cpp-python and ctransformers with LangChain:
 
+* [LangChain + llama-cpp-python](https://python.langchain.com/docs/integrations/llms/llamacpp)
 
 <!-- README_GGUF.md-how-to-run end -->