using System; using System.Buffers; using System.Collections.Generic; using System.Diagnostics; using System.IO; using System.Runtime.InteropServices; using System.Text; using LLama.Exceptions; using LLama.Extensions; namespace LLama.Native { /// /// A reference to a set of llama model weights /// // ReSharper disable once ClassNeverInstantiated.Global (used implicitly in native API) public sealed class SafeLlamaModelHandle : SafeLLamaHandleBase { /// /// Total number of tokens in vocabulary of this model /// public int VocabCount => llama_n_vocab(this); /// /// Total number of tokens in the context /// public int ContextSize => llama_n_ctx_train(this); /// /// Get the rope frequency this model was trained with /// public float RopeFrequency => llama_rope_freq_scale_train(this); /// /// Dimension of embedding vectors /// public int EmbeddingSize => llama_n_embd(this); /// /// Get the size of this model in bytes /// public ulong SizeInBytes => llama_model_size(this); /// /// Get the number of parameters in this model /// public ulong ParameterCount => llama_model_n_params(this); /// /// Get a description of this model /// public string Description { get { unsafe { // Get description length var size = llama_model_desc(this, null, 0); var buf = new byte[size + 1]; fixed (byte* bufPtr = buf) { size = llama_model_desc(this, bufPtr, buf.Length); return Encoding.UTF8.GetString(buf, 0, size); } } } } /// /// Get the number of metadata key/value pairs /// /// public int MetadataCount => llama_model_meta_count(this); /// protected override bool ReleaseHandle() { llama_free_model(handle); return true; } /// /// Load a model from the given file path into memory /// /// /// /// /// public static SafeLlamaModelHandle LoadFromFile(string modelPath, LLamaModelParams lparams) { // Try to open the model file, this will check: // - File exists (automatically throws FileNotFoundException) // - File is readable (explicit check) // This provides better error messages that llama.cpp, which would throw an access violation exception in both cases. using (var fs = new FileStream(modelPath, FileMode.Open)) if (!fs.CanRead) throw new InvalidOperationException($"Model file '{modelPath}' is not readable"); return llama_load_model_from_file(modelPath, lparams) ?? throw new LoadWeightsFailedException($"Failed to load model {modelPath}."); } #region native API static SafeLlamaModelHandle() { // This ensures that `NativeApi` has been loaded before calling the two native methods below NativeApi.llama_empty_call(); } /// /// Load all of the weights of a model into memory. /// /// /// /// The loaded model, or null on failure. [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] private static extern SafeLlamaModelHandle llama_load_model_from_file(string path_model, LLamaModelParams @params); /// /// Apply a LoRA adapter to a loaded model /// path_base_model is the path to a higher quality model to use as a base for /// the layers modified by the adapter. Can be NULL to use the current loaded model. /// The model needs to be reloaded before applying a new adapter, otherwise the adapter /// will be applied on top of the previous one /// /// /// /// /// /// /// Returns 0 on success [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] public static extern int llama_model_apply_lora_from_file(SafeLlamaModelHandle model_ptr, string path_lora, float scale, string? path_base_model, int n_threads); /// /// Frees all allocated memory associated with a model /// /// [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] private static extern void llama_free_model(IntPtr model); /// /// Get the number of metadata key/value pairs /// /// /// [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] private static extern int llama_model_meta_count(SafeLlamaModelHandle model); /// /// Get metadata key name by index /// /// Model to fetch from /// Index of key to fetch /// buffer to write result into /// The length of the string on success (even if the buffer is too small). -1 is the key does not exist. private static int llama_model_meta_key_by_index(SafeLlamaModelHandle model, int index, Span dest) { unsafe { fixed (byte* destPtr = dest) { return llama_model_meta_key_by_index_native(model, index, destPtr, dest.Length); } } [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl, EntryPoint = "llama_model_meta_key_by_index")] static extern unsafe int llama_model_meta_key_by_index_native(SafeLlamaModelHandle model, int index, byte* buf, long buf_size); } /// /// Get metadata value as a string by index /// /// Model to fetch from /// Index of val to fetch /// Buffer to write result into /// The length of the string on success (even if the buffer is too small). -1 is the key does not exist. private static int llama_model_meta_val_str_by_index(SafeLlamaModelHandle model, int index, Span dest) { unsafe { fixed (byte* destPtr = dest) { return llama_model_meta_val_str_by_index_native(model, index, destPtr, dest.Length); } } [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl, EntryPoint = "llama_model_meta_val_str_by_index")] static extern unsafe int llama_model_meta_val_str_by_index_native(SafeLlamaModelHandle model, int index, byte* buf, long buf_size); } /// /// Get metadata value as a string by key name /// /// /// /// /// /// The length of the string on success, or -1 on failure [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] public static extern unsafe int llama_model_meta_val_str(SafeLlamaModelHandle model, byte* key, byte* buf, long buf_size); /// /// Get the number of tokens in the model vocabulary /// /// /// [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] private static extern int llama_n_vocab(SafeLlamaModelHandle model); /// /// Get the size of the context window for the model /// /// /// [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] private static extern int llama_n_ctx_train(SafeLlamaModelHandle model); /// /// Get the dimension of embedding vectors from this model /// /// /// [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] private static extern int llama_n_embd(SafeLlamaModelHandle model); /// /// Get a string describing the model type /// /// /// /// /// The length of the string on success (even if the buffer is too small)., or -1 on failure [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] private static extern unsafe int llama_model_desc(SafeLlamaModelHandle model, byte* buf, long buf_size); /// /// Get the size of the model in bytes /// /// /// The size of the model [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] private static extern ulong llama_model_size(SafeLlamaModelHandle model); /// /// Get the number of parameters in this model /// /// /// The functions return the length of the string on success, or -1 on failure [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] private static extern ulong llama_model_n_params(SafeLlamaModelHandle model); /// /// Get the model's RoPE frequency scaling factor /// /// /// [DllImport(NativeApi.libraryName, CallingConvention = CallingConvention.Cdecl)] private static extern float llama_rope_freq_scale_train(SafeLlamaModelHandle model); #endregion #region LoRA /// /// Apply a LoRA adapter to a loaded model /// /// /// /// A path to a higher quality model to use as a base for the layers modified by the /// adapter. Can be NULL to use the current loaded model. /// /// public void ApplyLoraFromFile(string lora, float scale, string? modelBase = null, int? threads = null) { var err = llama_model_apply_lora_from_file( this, lora, scale, string.IsNullOrEmpty(modelBase) ? null : modelBase, threads ?? Math.Max(1, Environment.ProcessorCount / 2) ); if (err != 0) throw new RuntimeError("Failed to apply lora adapter."); } #endregion #region tokenize /// /// Convert a single llama token into bytes /// /// Token to decode /// A span to attempt to write into. If this is too small nothing will be written /// The size of this token. **nothing will be written** if this is larger than `dest` public uint TokenToSpan(LLamaToken token, Span dest) { var length = NativeApi.llama_token_to_piece(this, token, dest); return (uint)Math.Abs(length); } /// /// Convert a sequence of tokens into characters. /// /// /// /// /// The section of the span which has valid data in it. /// If there was insufficient space in the output span this will be /// filled with as many characters as possible, starting from the _last_ token. /// [Obsolete("Use a StreamingTokenDecoder instead")] internal Span TokensToSpan(IReadOnlyList tokens, Span dest, Encoding encoding) { var decoder = new StreamingTokenDecoder(encoding, this); decoder.AddRange(tokens); var str = decoder.Read(); if (str.Length < dest.Length) { str.AsSpan().CopyTo(dest); return dest.Slice(0, str.Length); } else { str.AsSpan().Slice(str.Length - dest.Length).CopyTo(dest); return dest; } } /// /// Convert a string of text into tokens /// /// /// /// /// Allow tokenizing special and/or control tokens which otherwise are not exposed and treated as plaintext. /// public LLamaToken[] Tokenize(string text, bool add_bos, bool special, Encoding encoding) { // Early exit if there's no work to do if (text == "" && !add_bos) return Array.Empty(); // Convert string to bytes, adding one extra byte to the end (null terminator) var bytesCount = encoding.GetByteCount(text); var bytes = ArrayPool.Shared.Rent(bytesCount + 1); try { unsafe { fixed (char* textPtr = text) fixed (byte* bytesPtr = bytes) { // Convert text into bytes encoding.GetBytes(textPtr, text.Length, bytesPtr, bytes.Length); // Tokenize once with no output, to get the token count. Output will be negative (indicating that there was insufficient space) var count = -NativeApi.llama_tokenize(this, bytesPtr, bytesCount, (LLamaToken*)IntPtr.Zero, 0, add_bos, special); // Tokenize again, this time outputting into an array of exactly the right size var tokens = new LLamaToken[count]; fixed (LLamaToken* tokensPtr = tokens) { NativeApi.llama_tokenize(this, bytesPtr, bytesCount, tokensPtr, count, add_bos, special); return tokens; } } } } finally { ArrayPool.Shared.Return(bytes, true); } } #endregion #region context /// /// Create a new context for this model /// /// /// public SafeLLamaContextHandle CreateContext(LLamaContextParams @params) { return SafeLLamaContextHandle.Create(this, @params); } #endregion #region metadata /// /// Get the metadata key for the given index /// /// The index to get /// The key, null if there is no such key or if the buffer was too small public Memory? MetadataKeyByIndex(int index) { // Check if the key exists, without getting any bytes of data var keyLength = llama_model_meta_key_by_index(this, index, Array.Empty()); if (keyLength < 0) return null; // get a buffer large enough to hold it var buffer = new byte[keyLength + 1]; keyLength = llama_model_meta_key_by_index(this, index, buffer); Debug.Assert(keyLength >= 0); return buffer.AsMemory().Slice(0, keyLength); } /// /// Get the metadata value for the given index /// /// The index to get /// The value, null if there is no such value or if the buffer was too small public Memory? MetadataValueByIndex(int index) { // Check if the key exists, without getting any bytes of data var valueLength = llama_model_meta_val_str_by_index(this, index, Array.Empty()); if (valueLength < 0) return null; // get a buffer large enough to hold it var buffer = new byte[valueLength + 1]; valueLength = llama_model_meta_val_str_by_index(this, index, buffer); Debug.Assert(valueLength >= 0); return buffer.AsMemory().Slice(0, valueLength); } internal IReadOnlyDictionary ReadMetadata() { var result = new Dictionary(); for (var i = 0; i < MetadataCount; i++) { var keyBytes = MetadataKeyByIndex(i); if (keyBytes == null) continue; var key = Encoding.UTF8.GetStringFromSpan(keyBytes.Value.Span); var valBytes = MetadataValueByIndex(i); if (valBytes == null) continue; var val = Encoding.UTF8.GetStringFromSpan(valBytes.Value.Span); result[key] = val; } return result; } #endregion } }