LoRA Adapters

This page covers the LoRA (Low-Rank Adaptation) adapter system in LLamaSharp: how adapters are loaded from disk, associated with a model, applied to or removed from inference contexts, and how control vectors differ from LoRA adapters.

For general model loading, see Model Loading and LLamaWeights. For context creation and inference, see Context Management and LLamaContext. For the SafeHandle pattern underlying these types, see Memory Management and SafeHandles.

---

Overview

LoRA adapters are small weight-delta files that modify the behavior of a base model without reloading the full weights. In LLamaSharp, the process is split across two managed types:

• SafeLlamaModelHandle — loads and owns the adapter file.
• SafeLLamaContextHandle — activates or deactivates adapters per inference context.

This split allows a single loaded adapter to be applied to multiple contexts simultaneously, or applied at different scales in different contexts, all without reloading the adapter file.

Object relationship diagram: LoRA adapter data flow

Sources: LLama/Native/SafeLlamaModelHandle.cs421-483 LLama/Native/SafeLLamaContextHandle.cs347-476 LLama/Native/LoraAdapter.cs8-36

---

Loading an Adapter

Adapters are loaded at the model level. SafeLlamaModelHandle.LoadLoraFromFile validates that the file is readable, calls the native llama_adapter_lora_init, and wraps the result in a LoraAdapter object LLama/Native/SafeLlamaModelHandle.cs461-483

SafeLlamaModelHandle.LoadLoraFromFile(path)
 → validates file is readable
 → llama_adapter_lora_init(SafeLlamaModelHandle model, string path) [native]
 → returns LoraAdapter(model, path, ptr)

The LoraAdapter object LLama/Native/LoraAdapter.cs8-36 holds:

Member	Purpose
Model	The SafeLlamaModelHandle this adapter belongs to
Path	The full path of the file this adapter was loaded from
Pointer	Raw IntPtr pointing to the native llama_adapter_lora*
Loaded	Whether the adapter is still valid and not unloaded

LLamaWeights does not expose LoadLoraFromFile directly; callers must go through LLamaWeights.NativeHandle LLama/LLamaWeights.cs24 to reach SafeLlamaModelHandle.LoadLoraFromFile LLama/Native/SafeLlamaModelHandle.cs461-483

Sources: LLama/Native/LoraAdapter.cs8-36 LLama/Native/SafeLlamaModelHandle.cs461-483 LLama/LLamaWeights.cs24

---

Applying Adapters to a Context

Adapters are activated per context, not per model. This means different LLamaContext / SafeLLamaContextHandle instances sharing the same weights can have different LoRA adapters active simultaneously.

Sequence diagram: applying a LoRA adapter

Sources: LLama/Native/SafeLLamaContextHandle.cs435-453

AddLoraAdapter

• Validates that lora.Model is the same object as the context's ModelHandle LLama/Native/SafeLLamaContextHandle.cs443-444 Passing an adapter from a different model throws ArgumentException.
• Validates that lora.Loaded is true LLama/Native/SafeLLamaContextHandle.cs446-447 A disposed adapter throws ArgumentException.
• scale controls the strength of the adaptation. 1.0f applies the adapter at full strength.
• Calls llama_set_adapter_lora(this, lora.Pointer, scale) internally LLama/Native/SafeLLamaContextHandle.cs449
• Throws RuntimeError on native failure LLama/Native/SafeLLamaContextHandle.cs450-452

Sources: LLama/Native/SafeLLamaContextHandle.cs435-453

RemoveLoraAdapter

• Returns false if lora.Model does not match (no-op, no exception) LLama/Native/SafeLLamaContextHandle.cs460-461
• Calls llama_rm_adapter_lora(this, lora.Pointer) LLama/Native/SafeLLamaContextHandle.cs463
• Returns true if the adapter was found in this context and removed; false otherwise LLama/Native/SafeLLamaContextHandle.cs464-466

Sources: LLama/Native/SafeLLamaContextHandle.cs455-467

ClearLoraAdapters

• Removes all active LoRA adapters from the context in a single call.
• Calls llama_clear_adapter_lora(this) LLama/Native/SafeLLamaContextHandle.cs474
• No return value; always succeeds.

Sources: LLama/Native/SafeLLamaContextHandle.cs469-475

---

Native API Mapping

The table below maps managed methods to their native counterparts defined in the SafeLLamaContextHandle and SafeLlamaModelHandle native regions.

Managed method	Native function	Location
SafeLlamaModelHandle.LoadLoraFromFile	llama_adapter_lora_init	LLama/Native/SafeLlamaModelHandle.cs421
SafeLLamaContextHandle.AddLoraAdapter	llama_set_adapter_lora	LLama/Native/SafeLLamaContextHandle.cs347
SafeLLamaContextHandle.RemoveLoraAdapter	llama_rm_adapter_lora	LLama/Native/SafeLLamaContextHandle.cs391
SafeLLamaContextHandle.ClearLoraAdapters	llama_clear_adapter_lora	LLama/Native/SafeLLamaContextHandle.cs394

Diagram: native function mapping

Sources: LLama/Native/SafeLlamaModelHandle.cs420-422 LLama/Native/SafeLLamaContextHandle.cs346-394

---

Adapter Metadata

The native layer exposes metadata on loaded adapter objects. These are surfaced in SafeLLamaContextHandle as private P/Invokes available for internal use:

Native function	Description
llama_adapter_meta_count	Number of key/value pairs in the adapter's metadata
llama_adapter_meta_key_by_index	Key string at a given index
llama_adapter_meta_val_by_index	Value string at a given index
llama_adapter_meta_val_str	Value string for a named key

These functions take the raw IntPtr adapter (the LoraAdapter.Pointer), not a SafeLLamaContextHandle.

Sources: LLama/Native/SafeLLamaContextHandle.cs349-388

---

Control Vectors vs. LoRA Adapters

Control vectors (llama_apply_adapter_cvec) are a different mechanism from LoRA. Both influence model outputs, but they operate differently.

Property	LoRA Adapters	Control Vectors
Load site	Model (SafeLlamaModelHandle)	Caller-provided float buffer
Apply site	Context (SafeLLamaContextHandle)	Context (SafeLLamaContextHandle)
File format	Separate GGUF adapter file	Raw float array
Layer targeting	Implicit in adapter	Explicit il_start / il_end range
Native function	llama_set_adapter_lora	llama_apply_adapter_cvec
Managed wrapper	LoraAdapter class	None; direct NativeApi call

Control vectors are applied via NativeApi.llama_apply_adapter_cvec LLama/Native/NativeApi.cs314:

• data: pointer to an n_embd × n_layers float buffer starting from layer 1.
• n_embd: the embedding dimension of a single layer's control.
• il_start / il_end: inclusive layer range to apply the vector to.
• Passing data = null (zero pointer) clears the currently loaded control vector.

Sources: LLama/Native/NativeApi.cs308-314

---

Ownership and Lifecycle

Loading
LoadLoraFromFile returns a LoraAdapter LLama/Native/SafeLlamaModelHandle.cs461-483 The caller owns this object and is responsible for its lifetime. The LoraAdapter holds the native pointer and the back-reference to the SafeLlamaModelHandle that created it LLama/Native/LoraAdapter.cs30-36

Validation
AddLoraAdapter checks lora.Model == ModelHandle before calling into native code LLama/Native/SafeLLamaContextHandle.cs443-444 This prevents applying an adapter loaded for model A to a context running model B, which would be undefined behavior at the native level.

Unloading
An adapter can be manually unloaded via LoraAdapter.Unload() LLama/Native/LoraAdapter.cs41-50 This sets Loaded to false and calls the native free function llama_adapter_lora_free LLama/Native/LoraAdapter.cs44-50 Note that adapters are also automatically freed when the associated model is unloaded LLama/Native/LoraAdapter.cs49

Multiple adapters
Multiple LoRA adapters can be active on a single context simultaneously. Each AddLoraAdapter call adds one adapter at a specified scale LLama/Native/SafeLLamaContextHandle.cs443-453 They compose additively at the native layer.

Sources: LLama/Native/LoraAdapter.cs41-50 LLama/Native/SafeLLamaContextHandle.cs443-476 LLama/Native/SafeLlamaModelHandle.cs461-483