README.md

---
language:
- en
model_creator: Meta
quantized_by: jartine
base_model: facebook/llm-compiler-13b-ftd
license: other
license_link: LICENSE
tags:
- llamafile
---

# LLM Compiler 13b FTD - llamafile

LLM Compiler is a large language model that's been trained to know how
to read/write AT&T style assembly, LLVM IR, and C code. It's able to
replicate the functionality of the clang compiler.

- Model creator: [Meta](https://llama.meta.com/)
- Original model: [facebook/llm-compiler-13b-ftd](https://huggingface.co/facebook/llm-compiler-13b-ftd)

The model is packaged by Mozilla into executable weights, which we call
[llamafiles](https://github.com/Mozilla-Ocho/llamafile)). This makes it
easy to use the model on Linux, MacOS, Windows, FreeBSD, OpenBSD, and
NetBSD for AMD64 and ARM64.

## Quickstart

Running the following on a desktop OS will launch a tab in your web
browser with a chatbot interface.

```
chmod +x llm-compiler-13b-ftd.Q6_K.llamafile
./llm-compiler-13b-ftd.Q6_K.llamafile --help
```

This model has a max context window size of 16k tokens. The `.args` file
inside these llamafiles have been configured to specify `-c 0 --temp 0`
so that the max context size is used by default, and randomness is
disabled by default too (since it's unhelpful for this model).

On GPUs with sufficient RAM, the `-ngl 999` flag may be passed to use
the system's NVIDIA or AMD GPU(s). On Windows, only the graphics card
driver needs to be installed. If the prebuilt DSOs should fail, the CUDA
or ROCm SDKs may need to be installed, in which case llamafile builds a
native module just for your system.

For further information, please see the [llamafile
README](https://github.com/mozilla-ocho/llamafile/).

Having **trouble?** See the ["Gotchas"
section](https://github.com/mozilla-ocho/llamafile/?tab=readme-ov-file#gotchas)
of the README.

## Prompting

LLM Compiler must be prompted *exactly* as Facebook describes in their
documentation. Any deviation from the character layout may cause the
model to stop working.

Temperature should be set to zero, otherwise the model will make very
poor decisions.

LLM Compiler is sensitive to the style of assembly. Facebook trained
this using clang, so `clang -S` will work best, even though the model
does appear to be a little bit friendly to `gcc -S` output.

### Assembly -> Assembly

To make things simple, here's an example of a shell script that can be
used to ask LLM Compiler to rewrite assembly code to be optimized. In
this case, we'll have it optimize `isxdigit()` which has been renamed to
minimize any hinting.

```sh
#!/bin/sh

cat >/tmp/hiho.c <<'EOF' || exit
int hiho(int c) {
  return ('0' <= c && c <= '9') ||
         ('A' <= c && c <= 'F') ||
         ('a' <= c && c <= 'f');
}
EOF

clang -c -o /tmp/hiho.o /tmp/hiho.c || exit
clang -S -o /tmp/hiho.s /tmp/hiho.c || exit

code=$(cat /tmp/hiho.s)
instruction_count=$(obj /tmp/hiho.o | grep -P '\t.*\t' | wc -l)
binary_size=$(size /tmp/hiho.o | tail -n1 | awk '{print $1}')

./llm-compiler-13b-ftd.Q6_K.llamafile \
-p "[INST] Optimize the following assembly to minimize code size:
<code>${code}</code>
The input code has instruction count ${instruction_count} and binary size ${binary_size} bytes.[/INST]"
```

The input file generated by clang (`/tmp/foo.s`) is 60 lines long. The
output produced by the LLM will be ~20 lines and 100% correct if tested.
This code will be fast and its size should only 3 bytes larger than what
`gcc -Os` is able to produce.

### C -> Assembly

LLM Compiler also understands how to read and write LLVM IR code. It can
also compile and decompile C code. Here's an example of how to do that.

```sh
#!/bin/sh

cat >/tmp/foo.c <<'EOF' || exit
int hiho(int c) {
  return ('0' <= c && c <= '9') ||
         ('A' <= c && c <= 'F') ||
         ('a' <= c && c <= 'f');
}
EOF

clang -c -o /tmp/foo.o /tmp/foo.c || exit
clang -S -o /tmp/foo.s /tmp/foo.c || exit

code=$(cat /tmp/foo.c)
instruction_count=$(obj /tmp/foo.o | grep -P '\t.*\t' | wc -l)
binary_size=$(size /tmp/foo.o | tail -n1 | awk '{print $1}')

./llm-compiler-13b-ftd.F16.llamafile \
-p "[INST] Give the assembly for the following code when optimized to minimize code size:
<code>${code}</code>
The input code has instruction count ${instruction_count} and binary size ${binary_size} bytes.[/INST]"
```

The output in this case looks like `clang -O0` output, despite the
prompt. Another option is to put in the prompt `when optimized by opt -p
'module(default<Oz>)'` which is what Facebook suggests in their
[`llm_compiler_demo.py`](https://huggingface.co/facebook/llm-compiler-13b-ftd/blob/main/llm_compiler_demo.py)
file.

## About llamafile

llamafile is a new format introduced by Mozilla Ocho on Nov 20th 2023.
It uses Cosmopolitan Libc to turn LLM weights into runnable llama.cpp
binaries that run on the stock installs of six OSes for both ARM64 and
AMD64.

## About Quantization Formats

The best quantization format for this model appears to be Q6\_0, which
appears to produce results consistent with full quality BF16/F16 weights
except Q6 goes much faster, for both prefill and prediction, by virtue
of consuming significantly less memory.

### Q6\_K, F16, BF16

The output for the first xdigit() assembly optimization example with
Q6\_K, F16, or BF16 weights is:

```asm
        .globl  hiho
hiho:   movl    %edi, %ecx
        movl    %ecx, %edi
        addl    $-48, %edi
        cmpl    $10, %edi
        setb    %al
        andl    $-33, %ecx
        addl    $-65, %ecx
        cmpl    $6, %ecx
        setb    %cl
        orb     %cl, %al
        andb    $1, %al
        movzbl  %al, %eax
        retq
```

This implementation is **CORRECT**. This implementation is **GOOD**.

NOTE: BF16 is currently only supported on CPU. It's the best quant for
prompt processing on Zen4.

### Q5\_0

The output for the first xdigit() assembly optimization example with
Q5\_0 weights is:

```asm
        .globl  hiho
hiho:   movl    %edi, %ecx
        movl    %ecx, -8(%rsp)
        addl    $-48, %ecx
        movb    $1, %al
        cmpl    $10, %ecx
        movb    %al, -1(%rsp)
        jb      .LBB0_3
        addl    $-65, %ecx
        movb    $1, %al
        cmpl    $6, %ecx
        jb      .LBB0_3
        addl    $-97, %eax
        cmpl    $6, %eax
        setb    %al
.LBB0_3:
        andb    $1, %al
        movzbl  %al, %eax
        retq
```

This implementation is **INCORRECT**. Even if it did work, it has
unneeded stack spillage and branches. Therefore this quantization format
was rejected and isn't included in this repository.

### Q5\_K\_M

The output for the first xdigit() assembly optimization example with
Q5\_K\_M weights is:

```asm
	.globl	hiho
hiho:   movl    $48, %eax
        cmpl    %edi, %eax
        setle   %cl
        cmpl    $57, %edi
        setle   %al
        andb    %al, %cl
        movb    $1, %al
        testb   $1, %cl
        jne     .LBB0_4
        movl    $65, %eax
        cmpl    %ecx, %eax
        setle   %cl
        cmpl    $70, -4(%rsp)
        setle   %al
        andb    %al, %cl
        movb    $1, %al
        testb   $1, %cl
        jne     .LBB0_4
        xorl    %eax, %eax
        movl    $97, %ecx
        cmpl    %edx, %ecx
        jg      .LBB0_4
        cmpl    $102, %eax
        setle   %al
.LBB0_4:
        andb    $1, %al
        movzbl  %al, %eax
        retq
```

This implementation is **INCORRECT**. Even if it did work, it has
unneeded stack spillage and branches. Therefore this quantization format
was rejected and isn't included in this repository.

### Q8\_0

The output for the first xdigit() assembly optimization example with
Q8\_0 weights is:

```asm
        .globl  hiho
hiho:   movl    $48, %eax
        cmpl    %edi, %eax
        setle   %cl
        cmpl    $57, %edi
        setle   %al
        andb    %al, %cl
        movb    $1, %al
        testb   $1, %cl
        jne     .LBB0_4
        movl    $65, %eax
        cmpl    %ecx, %eax
        setle   %cl
        cmpl    $70, -4(%rsp)
        setle   %al
        andb    %al, %cl
        movb    $1, %al
        testb   $1, %cl
        jne     .LBB0_4
        xorl    %eax, %eax
        movl    $97, %ecx
        cmpl    %edx, %ecx
        jg      .LBB0_4
        cmpl    $102, %eax
        setle   %al
.LBB0_4:
        andb    $1, %al
        movzbl  %al, %eax
        retq
```

This implementation is **INCORRECT**. Even if it did work, it has
unneeded stack spillage and branches. Therefore this quantization format
was rejected and isn't included in this repository.

---

# Introducing Meta Large Language Model Compiler (LLM Compiler), a state-of-the-art LLM for compiler optimization

## Takeaways

* LLM Compiler is a state-of-the-art LLM that builds upon Code Llama with improved performance for code optimization and compiler reasoning.
* LLM Compiler is free for both research and commercial use.
* LLM Compiler is available in two flavors:
    * _LLM Compiler_, the foundational models, pretrained on over 500B tokens of LLVM-IR, x86_84, ARM, and CUDA assembly codes and trained to predict the effect of LLVM optimizations;
    * and _LLM Compiler FTD_, which is further fine-tuned to predict the best optimizations for code in LLVM assembly to reduce code size, and to disassemble assembly code to LLVM-IR.
* LLM Compiler demonstrates far stronger understanding of compiler optimizations than existing publicly available LLMs, perfectly emulating the compiler 20% of the time.
* LLM Compiler FTD sets state-of-the-art results on the tasks of optimization for code size and disassembly. It achieves a 5.24% code size improvement over -Oz vs GPT-4 Turbo 0.03%, and 0.96 round-trip BLEU score on disassembly vs GPT-4 Turbo 0.43.


---

LINKS

* [LLM Compiler research paper](https://ai.meta.com/research/publications/meta-large-language-model-compiler-foundation-models-of-compiler-optimization/)
* Download the LLM Compiler and LLM Compiler FTD models:
    * [llm-compiler-7b](https://huggingface.co/facebook/llm-compiler-7b)
    * [llm-compiler-7b-ftd](https://huggingface.co/facebook/llm-compiler-7b-ftd)
    * [llm-compiler-13b](https://huggingface.co/facebook/llm-compiler-13b)
    * [llm-compiler-13b-ftd](https://huggingface.co/facebook/llm-compiler-13b-ftd)


---

We are excited to announce the release of LLM Compiler, a model targeted at code and compiler optimization tasks. LLM Compiler is built on top of our state-of-the-art large language model, Code Llama, adding capabilities to better understand compiler intermediate representations, assembly language and optimization. LLM Compiler is demonstrated on two difficult tasks: optimizing for code size and decompiling from assembly to the compiler’s intermediate representation. We release these foundation models to accelerate the application of LLMs for code optimization tasks and to enhance developer experience.

We are releasing LLM Compiler under the [LLM Compiler License Agreement](LICENSE.pdf), which incorporates the [Acceptable Use Policy]([https://llama.meta.com/llama3/use-policy]) for Llama Materials.

## How LLM Compiler works

LLM Compiler is a specialization of Code Llama. It is a cutting-edge tool designed to optimize code using deep learning. LLM Compiler has been pre-trained on a vast amount of LLVM assembly (IR), x86_64, ARM, and CUDA assembly codes. LLM Compiler can predict, given a piece of LLVM assembly and a sequence of optimization passes for `opt`, the LLVM optimizer, what the change in code size will be and what the output code will look like after applying these optimizations. It has ‘understood’ the behavior of the optimizing compiler to such a degree that in many cases it can perfectly replicate its output. These capabilities make it ideally suited to compiler optimization tasks. 

![Compiler emulation](readme/emulate.png)


In addition to this core functionality and to demonstrate its ability to solve complex compiler optimization problems, LLM Compiler has been fine-tuned for two specific downstream tasks:

1. Predicting the best optimization passes for `opt` to use in order to minimize code size, given a piece of LLVM assembly code. \

![Autotuning](readme/autotune.png)

2. Generating LLVM IR from a piece of x86_64 or ARM assembly code. \

![Disassemble](readme/disassemble.png)

We are releasing LLM Compiler models in two sizes: 7B and 13B parameters. The models have been trained with a context window of 16,000 tokens.

The two models address different serving and latency requirements. The 7B model, for example, can be served on a single GPU and is more suitable for tasks that require low latency, like fine grained optimisation. The 13B model returns the best results.

When using the LLM Compiler models, users must abide by our license and acceptable use policy.

![Training](readme/training.png)



## LLM Compiler performance

We tested the performance of LLM Compiler models for emulating compiler transformations,  predicting optimal pass lists and decompiling intermediate representation on hold out test sets and compared them to Code Llama and GPT-4. We compare LLM Compiler Foundation to Code Llama Base and LLM Compiler FTD to Code Llama Instruct.

We evaluate LLM Compiler's ability to emulate compiler optimizations by giving it samples of unoptimized intermediate representation and a randomly generated list of optimizations. We then ask the model to generate the corresponding IR after the optimizations have been applied. In the table below we report the model's accuracy in reproducing the IR we would get from running _opt_. With very little knowledge of IR, Code Llama is unable to achieve high values while the LLM Compiler can generate character-by-character matches of expected assembly in 20% of the cases.


<table>
  <tr>
   <td>Model
   </td>
   <td>Size
   </td>
   <td>Accuracy at emulating compiler optimizations
   </td>
  </tr>
  <tr>
   <td>Code Llama
   </td>
   <td>7B
   </td>
   <td>1.2%
   </td>
  </tr>
  <tr>
   <td>Code Llama
   </td>
   <td>13B
   </td>
   <td>0.8%
   </td>
  </tr>
  <tr>
   <td>LLM Compiler
   </td>
   <td>7B
   </td>
   <td>16%
   </td>
  </tr>
  <tr>
   <td>LLM Compiler
   </td>
   <td>13B
   </td>
   <td><strong>20%</strong>
   </td>
  </tr>
</table>


In a similar approach we evaluate our model's ability to optimize IR for code size. In this instance, however, we let the model generate the pass list that is to be used on a given unoptimized IR. We then use this pass list to optimize the particular program using _opt_ and record the binary size. The baseline is the binary size of the program when optimized using -Oz. Only LLM Compiler FTD models provide an improvement over -Oz, with the 13B parameter model marginally outperforming the smaller model, generating smaller object files than -Oz in 61% of cases.

Lastly, we evaluate disassembly performance by giving the model x86 assembly code and ask it to generate the corresponding IR. We then round-trip the model-generated disassembled IR back down to assembly. This enables us to evaluate accuracy of the disassembly by comparing the BLEU score of the original assembly against the round-trip result. LLM Compiler FTD 13B has the highest accuracy of round-tripped assembly (_round trip BLEU_) and most frequently produces perfect disassembly. Code Llama Instruct and GPT-4 Turbo struggle with generating syntactically correct LLVM-IR.


<table>
  <tr>
   <td>Model
   </td>
   <td>Size
   </td>
   <td>Code Size Improvement
   </td>
   <td>Round trip BLEU
   </td>
  </tr>
  <tr>
   <td>GPT-4 Turbo
   </td>
   <td>
   </td>
   <td>-0.01%
   </td>
   <td>0.43
   </td>
  </tr>
  <tr>
   <td>Code Llama Inst
   </td>
   <td>7B
   </td>
   <td>-0.49%
   </td>
   <td>0.48
   </td>
  </tr>
  <tr>
   <td>Code Llama Inst
   </td>
   <td>13B
   </td>
   <td>-0.42%
   </td>
   <td>0.62
   </td>
  </tr>
  <tr>
   <td>LLM Compiler FTD
   </td>
   <td>7B
   </td>
   <td>4.77%
   </td>
   <td>0.95
   </td>
  </tr>
  <tr>
   <td>LLM Compiler FTD
   </td>
   <td>13B
   </td>
   <td><strong>4.88%</strong>
   </td>
   <td><strong>0.96</strong>
   </td>
  </tr>
</table>



## Releasing LLM Compiler

LLMs are being used to make programming easier. They are beginning to be used to make programs more efficient.

At Meta, our conviction is that AI models, especially those designed for coding, thrive best with an open strategy, fostering both innovation and security. Models that are accessible to the public can expedite the creation of novel compiler optimization technologies. In turn, this will allow programs to be more efficient and smaller, enhancing the quality of life for all. By making models such as LLM Compiler available, the whole community can explore their potential, pinpoint problems, and rectify any vulnerabilities.

The model weights are available on Hugging Face.


## Responsible use

Our research paper provides an in-depth look into the development process of the LLM Compiler, the methods we used for our benchmarking tests, and further insights into the model's limitations. It also discusses the issues faced, the steps we took to mitigate them.

Developers are advised to assess their models using evaluation benchmarks specific to compilers. Given that compilers are not bug-free, any suggested compiler optimizations must be rigorously tested. When a model decompiles assembly code, its accuracy should be confirmed.


## The future of generative AI for optimisation

LLM Compiler is designed to support compiler researchers and engineers. But there are still many more use cases to support than what our models can serve. We hope that LLM Compiler will inspire others to leverage LLMs to create new innovative tools for research and commercial products.


### Try LLM Compiler today

* Download the LLM Compiler and LLM Compiler FTD models:
    * [llm-compiler-7b](https://huggingface.co/facebook/llm-compiler-7b)
    * [llm-compiler-7b-ftd](https://huggingface.co/facebook/llm-compiler-7b-ftd)
    * [llm-compiler-13b](https://huggingface.co/facebook/llm-compiler-13b)
    * [llm-compiler-13b-ftd](https://huggingface.co/facebook/llm-compiler-13b-ftd)

* Read the research paper
    * [LLM Compiler research paper](https://ai.meta.com/research/publications/meta-large-language-model-compiler-foundation-models-of-compiler-optimization/)


# **Model Card**

LLM Compiler is a collection of pretrained and fine-tuned generative text models ranging in scale from 7 billion to 13 billion parameters. This is the repository for the 13 billion parameter code size and disassembly fine-tuned model version in the Hugging Face Transformers format. This model is designed for code optimization. Links to other models can be found in the index at the bottom.

| Number of parameters | Base Model                                                                               | Fine-tuned for code size and dissassembly                                                       |
| -------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| 7B                   | [facebook/llm-compiler-7b](https://huggingface.co/facebook/llm-compiler-7b)    | [facebook/llm-compiler-7b-ftd](https://huggingface.co/facebook/llm-compiler-7b-ftd)   |
| 13B                  | [facebook/llm-compiler-13b](https://huggingface.co/facebook/llm-compiler-13b) | [facebook/llm-compiler-13b-ftd](https://huggingface.co/facebook/llm-compiler-13b-ftd) |


## Model Use

To use this model, please make sure to install transformers:

```bash
pip install transformers accelerate
```

Example code using each of the model's compiler capabilities may be found in [llm_compiler_demo.py](llm_compiler_demo.py).

The code below demonstrates default capabilities. You may need to set the HuggingFace access token - see (https://huggingface.co/docs/hub/security-tokens).

```python
from transformers import AutoTokenizer
import transformers
import torch

model = "facebook/llm-compiler-13b-ftd"

tokenizer = AutoTokenizer.from_pretrained(model)
pipeline = transformers.pipeline(
    "text-generation",
    model=model,
    torch_dtype=torch.float16,
    device_map="auto",
)

sequences = pipeline(
    '%3 = alloca i32, align 4',
    do_sample=True,
    top_k=10,
    temperature=0.1,
    top_p=0.95,
    num_return_sequences=1,
    eos_token_id=tokenizer.eos_token_id,
    max_length=200,
)
for seq in sequences:
    print(f"Result: {seq['generated_text']}")
```

## Model Details

*Note: Use of this model is governed by the Meta license. Meta developed and publicly released the LLM Compiler family of large language models (LLMs).

**Model Developers** Meta

**Variations** LLM Compiler comes in two model sizes of 7B, 13B parameters in two flavors, the foundation and instruction fine-tuned for code size and disassembly.

**This repository contains the 13 billion parameter code size and disassembly fine-tuned model.**

**Input** Models input text only.

**Example prompt** See `llm_compiler_demo.py` in the repo for examples of the different use cases.

**Output** Models generate text only.

**Model Architecture** LLM Compiler is an auto-regressive language model that uses an optimized transformer architecture.

**Model Dates** LLM Compiler has been trained between January 2024 and June 2024.

**Status** This is a static model trained on an offline dataset. 

**License** A custom commercial license is available at: [https://ai.meta.com/resources/models-and-libraries/llama-downloads/](https://ai.meta.com/resources/models-and-libraries/llama-downloads/)

**Research Paper** More information can be found in the paper "[Meta Large Language Model Compiler: Foundation Models of Compiler Optimization](https://ai.meta.com/research/publications/meta-large-language-model-compiler-foundation-models-of-compiler-optimization/)".

## Intended Use

**Intended Use Cases** LLM Compiler is intended for commercial and research use in English, relevant programming languages, LLVM IR, x86_64 assembly and ARM assembly.

**Out-of-Scope Uses** Use in any manner that violates applicable laws or regulations (including trade compliance laws). Use in languages other than English. Use in any other way that is prohibited by the [Acceptable Use Policy](https://llama.meta.com/llama3/use-policy) and Licensing Agreement for LLM Compiler and its variants.

## Hardware and Software

**Training Factors** We used custom training libraries. The training and fine-tuning of the released models have been performed Meta’s Research Super Cluster.

**Carbon Footprint** In aggregate, training all LLM Compiler models required 14K GPU hours of computation on hardware of type A100-80GB (TDP of 350-400W), not including the training of Code Llama. 100% of the estimated tCO2eq emissions were offset by Meta’s sustainability program.

## Training Data

All experiments reported here and the released models have been trained and fine-tuned using the same data as Code Llama with different weights (see Section 2 and Table 1 in the [research paper](https://ai.meta.com/research/publications/llm-compiler-foundation-models-for-compiler-optimization/) for details).

## Evaluation Results

See evaluations for the main models and detailed ablations in Section 3 and safety evaluations in Section 4 of the research paper.

## Ethical Considerations and Limitations

LLM Compiler and its variants are a new technology that carries risks with use. Testing conducted to date has been in English, and has not covered, nor could it cover all scenarios. For these reasons, as with all LLMs, LLM Compilers’s potential outputs cannot be predicted in advance, and the model may in some instances produce inaccurate or objectionable responses to user prompts. Therefore, before deploying any applications of LLM Compiler, developers should perform safety testing and tuning tailored to their specific applications of the model.

Please see the Responsible Use Guide available available at [https://ai.meta.com/llama/responsible-use-guide](https://ai.meta.com/llama/responsible-use-guide).