If you’ve ever built a network layer in Swift, you’ve probably written the same URLSession code again and again. Or you tried to abstract it and ended up with something complicated, hard to extend, or full of enums and switch statements.

I developed RequestSpec, a lightweight library that makes networking both approachable and scalable without adding unnecessary complexity.

It gives you:

• A declarative way to define endpoints
• A lightweight NetworkService protocol
• Automatic URLRequest building
• A clean async/await API

In this post, we’ll build a tiny but realistic network layer using JSONPlaceholderService. You’ll define two real endpoints:

• GET /posts
• POST /posts

Let’s start.

Why a Generic Network Layer?

A good network layer makes your app:

• Easier to test
• Easier to understand
• Easier to extend

But it shouldn’t require dozens of generic types or a heavy framework. RequestSpec keeps things light: you only define small, focused request types and create a service that sends them.

1. Install RequestSpec

Add it via Swift Package Manager:

https://github.com/ibrahimcetin/RequestSpec

That’s all you need.

2. Define Your Models

struct BlogPost: Decodable {
    let id: Int
    let userId: Int
    let title: String
    let body: String
}

This is the model we receive from the API.
It conforms to Decodable because it will be parsed from JSON.

struct CreatePostInput: Encodable {
    let title: String
    let body: String
    let userId: Int
}

This is what we send to the server when creating a post.
It conforms to Encodable because it will be JSON encoded.

3. Create Your RequestSpecs

Each API endpoint becomes its own small struct that conforms to RequestSpec. This keeps things modular and avoids giant enums or switch statements.

GET Request (Fetch Posts)

struct GetPostsRequest: RequestSpec {
    var request: Get<[BlogPost]> {
        Get("posts")  // URL path segment
            .headers {
                Accept("application/json")  // Tell server we want JSON
                UserAgent("RequestSpec/1.0")  // Identify our client
            }
            .timeout(10)  // Wait max 10 seconds
    }
}

This tells RequestSpec:

• Use GET
• Call /posts
• Set headers
• Applies a timeout
• Decodes into [BlogPost]

POST Request (Create New Post)

struct CreatePostRequest: RequestSpec {
    let input: CreatePostInput  // Data to send
    
    var request: Post<BlogPost> {
        Post("posts")
            .body {
                input  // This gets JSON-encoded automatically!
            }
            .headers {
                ContentType("application/json")  // Tell server we're sending JSON
                UserAgent("RequestSpec/1.0")
            }
            .timeout(10)
    }
}

This one:

• Uses POST
• Calls /posts
• Sends the input data as JSON
• Sets headers
• Applies a timeout

That’s it.

4. Build the JSONPlaceholderService

RequestSpec provides a NetworkService protocol that you can conform to and use to send your requests.

We will inherit from it to create our service's protocol:

protocol JSONPlaceholderServiceProtocol: NetworkService {
    func getPosts() async throws -> [BlogPost]
    func createPost(_ input: CreatePostInput) async throws -> BlogPost
}

Having a protocol makes it easier to test and mock. You can create a mock implementation of the protocol and use it in your tests but we will use the real implementation for now.

Now we can implement the service:

final class JSONPlaceholderService: JSONPlaceholderServiceProtocol {
    let baseURL = URL(string: "https://jsonplaceholder.typicode.com")!
    let decoder: Decoder = JSONDecoder()
    let session: URLSession = URLSession.shared

    func getPosts() async throws -> [BlogPost] {
        let request = GetPostsRequest()
        let response = try await send(request)
        return response.body
    }

    func createPost(_ input: CreatePostInput) async throws -> BlogPost {
        let request = CreatePostRequest(input: input)
        let response = try await send(request)
        return response.body
    }
}

Here’s what you didn’t write:

• No URLSession code
• No URLRequests
• No JSONEncoder / JSONDecoder
• No manual path building
• No switch statements over enums

Everything goes through send(request).

5. Use the Service

let service = JSONPlaceholderService()
let posts = try await service.getPosts()
print(posts)

Readable. Type-safe. Clean.

Explore the Complete Example

RequestSpec/Examples/RequestSpecExample at main · ibrahimcetin/RequestSpec

Why RequestSpec Makes Networking Approachable

Here’s the philosophy:

Small types over giant enums

Every endpoint is its own struct which makes it easier to build, maintain, and reuse.

Zero boilerplate

No manual URLRequest creation. No decoding logic scattered everywhere.

Scales naturally

Adding a new endpoint means adding a new RequestSpec — nothing else.

Conclusion

I developed RequestSpec to make networking approachable and easy to understand. It has more features and is more powerful than this example but the core ideas are the same. You can check out the README for more details.

You don’t need to use RequestSpec exclusively. It is interoperable with other libraries like URLSession, Alamofire to use it in your existing project. You can check out the Examples directory.

Resources

• RequestSpec
• RequestSpec Examples

MLX Swift is able us to run LLMs as well as VLMs which is stands for Visual Language Models and these models can describe an image, detect an object, answer visual questions or extract text from image. Thank to MLX Swift, we can run these model directly in our apps without any server.

This blog post is the last in a three-part series where I’ll guide you through running VLMs with MLX Swift by developing a sample project.

You can find the other blog posts here:

1. MLX Swift: Run LLMs in iOS Apps
2. Run Hugging Face Models with MLX Swift
3. MLX Swift: Running VLMs (Image-to-Text) in iOS Apps

I am developing a sample project along with the posts. It will be minimal yet practical, so you’ll have a working reference at your fingertips.

GitHub - ibrahimcetin/MLXSampleApp

Tip: If you don’t know what is MLX Swift, you may want to check out the first blog post of the series.

Overview

The steps are same as running LLMs, only five steps:

1. Add MLX Swift Examples Package: This package provides the necessary modules and tools for running VLMs with MLX Swift.
2. Select a Model: Choose the model you want to use, whether an LLM or a VLM.
3. Download and Load the Model: Load the model weights and its configurations. (All process will be handled by MLXVLM)
4. Create an Input: Provide a prompt and an image for the model.
5. Run the Model: Process the input through the model and generate the output.

Adding MLX Swift Examples Package

Since MLX Swift Examples is an SPM package, you can add it directly in Xcode:

1. In Xcode, Go to File -> Add Package Dependencies…
2. Paste the following Package URL: https://github.com/ml-explore/mlx-swift-examples
3. Set the Dependency Rule to Branch and set it to main.
4. Add the MLXVLM package to your project’s target.

If you already added mlx-swift-examples package to your project, you can add MLXVLM from Target -> Frameworks, Libraries and Embedded Content menu.

Then, import the required modules in your file:

import MLXLLM
import MLXLMCommon

• MLXVLM will provide us VLM specific necessary items.
• MLXLMCommon is a common library to generate language model output. It works both LLMs and VLMs.

Selecting a Model

First, we need to choose the model we want to use:

let modelConfiguration: ModelConfiguration = ModelRegistry.qwen2_5Coder_1_5B_4bit

We create a ModelConfiguration instance for the selected model. MLXVLM includes predefined popular models in ModelRegistry.
Here, I chose Qwen2 VL 2B Instruct 4bit because it is a instruct model. That is, we can make conversation with it.

! Using a instruct model here will add a little bit complexity but I think it will be a better and more educational.

Recall: In the previous post, I show how to use other models from Hugging Face!

Loading the Selected Model

Using the modelConfiguration instance, we can load our model:

let modelContainer = try await VLMModelFactory.shared.loadContainer(
    configuration: modelConfiguration
) { progress in
    Task { @MainActor in
        self.downloadProgress = progress
    }
}

Here, we use VLMModelFactory instead of LLMModelFactory to load VLMs.

VLMModelFactory.shared.loadContainer method automatically downloads the model from Hugging Face if it is not available locally. It also handles creating the model with the appropriate architecture and loading the weights from .safetensors files. It also takes a closure to allow us to track the downloading progress.

Tip: VLMModelFactory and LLMModelFactory both conform to ModelFactory.

Preparing an Input

Firstly, we have to select the images we use. We can use PhotosUI package for iOS and fileImporter view modifier for macOS in SwiftUI:

import PhotosUI

@State private var showingPhotoPicker: Bool = false
@State private var photoSelection: PhotosPickerItem?

VStack {
  /* UI Code */
}
#if(os(iOS))
.photosPicker(isPresented: $showingPhotoPicker, selection: $photoSelection)
.onChange(of: photoSelection, addImage)
#elseif(os(macOS))
.fileImporter(isPresented: $showingPhotoPicker, allowedContentTypes: [.image], onCompletion: addImage)
#endif

• When an image is selected, the addImage will be called.

!!! To use these images as input, we need to convert them to CIImage. However, we also want to display them using the Image view. To achieve both, we store the selected images as Data. This allows us to convert them to CIImage when needed while also displaying them in the Image view using UIImage or NSImage:

@State private var selectedImages: [Data] = []

private func addImage() {
  Task {
      if let data = try? await photoSelection?.loadTransferable(type: Data.self) {
          selectedImages = [data]
      }
  }
}

Now, we can call generate method:

await vm.generate(prompt: prompt, images: selectedImages)

This is a boilerplate code don’t try to run it. You can find it in the sample project.

Creating an Input

To run our model, we need to provide an input:

let result = try await modelContainer.perform { context in
  // Create images and messages
  let images: [UserInput.Image] = images.compactMap { CIImage(data: $0) }.map { .ciImage($0) }
  let message: Message = [
      "role": "user",
      "content": [
          ["type": "text", "text": prompt]
      ] + images.map { _ in ["type": "image"] }
  ]

  // Create prompt
  let prompt = UserInput(messages: [message], images: images)
  prompt.processing.resize = CGSize(width: 448, height: 448)
  
  // Create input
  let input = try await context.processor.prepare(input: prompt)
  
  /* Generate output */
}

• We call modelContainer.perform, which allows us to interact with the ModelContext.
• Since the images are passed as Data, we need to convert them to CIImage and provide them as the .ciImage associated value.
• This time we use Message because the model we use is Qwen2 VL instruct model. That is, we have to use messages format for Qwen2 VL to add images. Alternatively, you can use models like Paligemma 3B mix which don’t require any format.
• We use UserInput to transform the prompt into an input format.
• Finally, we convert the prompt into an LMInput instance using context.processor.prepare, which will be used for generating the output.

Running the LLM Model

To run the model, we use the MLXLMCommon module:

/* Create input */
return try MLXLMCommon.generate(input: input, parameters: .init(), context: context) { tokens in
     let text = context.tokenizer.decode(tokens: tokens)

     Task { @MainActor in
        output = text
     }
     
     return .more
}

• MLXCommon.generate takes the input and the context from the perform method and generates the output inside the closure.
• The closure receives the encoded tokens, so we first decode them using the tokenizer before using the output.
• Finally, we return .more to continue generating output. If you want to stop generation — for example, when reaching a maximum token limit — you can return .stop instead.

Final Application

You can find the app I developed for this blog post here:

GitHub - ibrahimcetin/MLXSampleApp

Tip: Each blog post also has its own branch to make it easy to find the corresponding code for each part.

Limit The Buffer Cache

In MLX, managing the buffer cache is essential for optimal performance and memory usage. You can control the buffer cache size using the set(cacheLimit:) function, which specifies the maximum memory (in bytes) that the cache can utilize. For example, to limit the buffer cache to 200 megabytes, implement the following code:

MLX.GPU.set(cacheLimit: 20 * 1024 * 1024)

Adjusting the cache limit helps balance memory consumption and computational efficiency.

Moving Forward

MLX Swift offers much more beyond what we’ve covered. Here are a few things you can explore:

• Fine-tune generation parameters. If you missed it, we used them in MLXLMCommon.generate.
• Experiment with different models from the mlx-community page on Hugging Face.
• Convert models that haven’t been ported to MLX format yet and run them on Apple devices.

There’s plenty more to discover, so keep exploring!

Conclusion

That’s all from me for now! Don’t forget to check out the sample project. I believe that on-device language models will become more accessible and preferred in the future. Even now, they are at a usable level for many tasks. I truly believe that locally running models are the future.

To summarize, we:

• Learned the basics of running VLMs on-device with MLX Swift.
• Used a small instruct model, Qwen2 VL 2B Instruct 4bit.
• Prepared inputs and executed inference.

MLX Swift provides us some predefined models in ModelRegistry but these are very limited. If you want to use other models or try to latest ones, you have to add these models yourself. It is easy and straightforward, so don’t hesitate.

This blog post is the second in a three-part series where I’ll guide you through adding language models from Hugging Face to use with MLX Swift.

You can find the other blog posts here:

1. MLX Swift: Run LLMs in iOS Apps
2. Run Hugging Face Models with MLX Swift
3. MLX Swift: Running VLMs (Image-to-Text) in iOS Apps

I am developing a sample project along with the posts. It will be minimal yet practical, so you’ll have a working reference at your fingertips.

GitHub - ibrahimcetin/MLXSampleApp

Tip: If you don’t know what is MLX Swift, please checkout the first blog post of the series.

Adding Custom Models

Firstly, a model must be in MLX format to be usable. Fortunately, the MLX community does a great job of converting and sharing models in MLX format on Hugging Face. You can explore all available models from their HF page.

mlx-community (MLX Community)

Adding custom models are as simple as creating a ModelContext instance. The code example adds DeepSeek-R1 1.5B model:

extension ModelRegistry {
    static let deepSeekR1_1_5B_4bit = ModelConfiguration(
        id: "mlx-community/DeepSeek-R1-Distill-Qwen-1.5B-4bit",
        overrideTokenizer: "PreTrainedTokenizer",
        defaultPrompt: "Write a program that sends a request to google in python."
    )
}

• We define an extension on ModelRegistry and define a descriptive name such as deepSeekR1_1_5B_4bit as a static property to easily access to it.
• ModelConfiguration wants id at least from us and this is the name of the model from Hugging Face.
• The defaultPrompt is a predefined input and is used when no prompt is provided. (This field is optional, and if not set, it defaults to hello.)
• The overrideTokenizer parameter allows us to specify a custom tokenizer instead of using a default one. In this case, we set it to "PreTrainedTokenizer", meaning the model will use a tokenizer that has already been trained and configured, typically from its Hugging Face repository. This ensures the tokenizer matches the model’s architecture, vocabulary, and text-processing rules, preventing any mismatches in input handling.

Tip: You can investigate static variables on ModelRegistry to get more idea.

Using The Custom Model

First, we have to create an instance of the custom ModelConfiguration:

let customModelConfiguration = ModelRegistry.deepSeekR1_1_5B_4bit

Then, we can load and you it:

modelContainer = try await LLMModelFactory.shared.loadContainer(
    configuration: customModelConfiguration
) { progress in
    Task { @MainActor in
        self.downloadProgress = progress
    }
}

Lastly, run the model:

let result = try await modelContainer.perform { context in
    let prompt = UserInput(prompt: prompt)
    let input = try await context.processor.prepare(input: prompt)

    return try MLXLMCommon.generate(input: input, parameters: .init(), context: context) { tokens in
        let text = context.tokenizer.decode(tokens: tokens)

        Task { @MainActor in
            output = text
        }

        return .more
    }
}

Tip: For more details about how to run the model, be sure to check out my previous blog post.

Final Application

You can find the app I developed for this blog post here:

GitHub - ibrahimcetin/MLXSampleApp

Tip: Each blog post also has its own branch to make it easy to find the corresponding code for each part.

Further Reading

MLX Swift abstracts away most of the complexity for us. Even though I said it’s simple, there are actually many details in the background. For example, this is the configuration for Llama from MLXLLM codebase:

public struct LlamaConfiguration: Codable, Sendable {
    var hiddenSize: Int
    var hiddenLayers: Int
    var intermediateSize: Int
    var attentionHeads: Int
    var headDimensions: Int?
    var rmsNormEps: Float
    var vocabularySize: Int
    var kvHeads: Int
    var maxPositionEmbeddings: Int?
    var ropeTheta: Float = 10_000
    var ropeTraditional: Bool = false
    var ropeScaling: [String: StringOrNumber]?
    var tieWordEmbeddings: Bool = true
    var attentionBias: Bool = false
    var mlpBias: Bool = false
}

It contains a lot properties. If you want to go further, you can read this documentation.

Where Are Models Stored?

Models are stored in Documents directory of the application by default. That is, it is /Users/<username>/Documents on macOS and the application’s Documents directory on iOS and other platforms.

Fortunately, we can change the default directory.

First, we have to import Hub package:

import Hub

• This package provides us HubApi struct to configure download directory.

Then, create a HubApi instance:

let hub = HubApi(downloadBase: URL.downloadsDirectory.appending(path: "huggingface"))

• This will able us to download the models to Downloads directory on macOS and app’s sandbox directory on iOS.

Lastly, we can pass it to LLMModelFactory.shared.loadContainer method:

modelContainer = try await LLMModelFactory.shared.loadContainer(
    hub: hub,
    configuration: modelConfiguration
) {
  /* Handle Progress */
}

Conclusion

Adding and using other models with MLX Swift is this simple!
If you can’t find a model you’re looking for on the mlx-community page, you can also convert models to MLX format yourself, though that’s a topic for another blog post.

To summarize, we:

• Learned how to run custom models from Hugging Face with MLX Swift.
• Integrated the DeepSeek-R1 1.5B model
• Changed the default download directory.

In the next post, we’ll explore how to use VLMs (Image-to-Text)!

Today, large language models (LLMs) are mostly used via a web API, but running them directly on a device is also possible and it has several advantages:

• Privacy: Since models run on the device, user data never leaves the device for a remote server.
• Cost: No API usage fees, as the model does not run on a cloud server.
• Offline Functionality: Once downloaded, models can continue running completely offline.

MLX Swift makes it easy to run LLMs and VLMs (Visual Language Model) in Swift, and it is straightforward to use.

This blog post is the first in a three-part series where I’ll guide you through running LLMs with MLX Swift by developing a sample project.

You can find the other blog posts here:

1. MLX Swift: Run LLMs in iOS Apps
2. Run Hugging Face Models with MLX Swift
3. MLX Swift: Run VLMs (Image-to-Text) in iOS Apps

The project will be minimal yet practical, so you’ll have a working reference at your fingertips.

GitHub - ibrahimcetin/MLXSampleApp

What Are MLX and MLX Swift?

MLX is a NumPy-like array framework developed by Apple for machine learning research, originally written in Python. It is optimized for Apple Silicon architecture.

MLX Swift is the Swift extension of MLX to make ML research and experimentation easier on Apple platforms. It allows us to run LLMs and VLMs in iOS and macOS apps easily.

Overview

There are only five steps to run language models:

1. Add MLX Swift Examples Package: This package provides the necessary modules and tools for running LLMs with MLX Swift.
2. Select a Model: Choose the model you want to use, whether an LLM or a VLM.
3. Download and Load the Model: Load the model weights and its configurations. (All process will be handled by MLXLLM)
4. Create an Input: Provide a prompt for the model.
5. Run the Model: Process the input through the model and generate the output.

Adding MLX Swift Examples Package

Since MLX Swift Examples is an SPM package, you can add it directly in Xcode:

1. In Xcode, Go to File -> Add Package Dependencies…
2. Paste the following Package URL: https://github.com/ml-explore/mlx-swift-examples
3. Set the Dependency Rule to Branch and set it to main.
4. Add the MLXLLM package to your project’s target.

Then, import the required modules in your file:

import MLXLLM
import MLXLMCommon

• MLXLLM will provide us LLM specific necessary items.
• MLXLMCommon is a common library to generate language model output. It works both LLMs and VLMs.

Selecting a Model

First, we need to choose the model we want to use:

let modelConfiguration: ModelConfiguration = ModelRegistry.llama3_2_1B_4bit

We create a ModelConfiguration instance for the selected model. MLXLLM includes predefined popular models in ModelRegistry.
Here, I chose Llama 3.2 1B 4-bit because it is a relatively small model.

Recall: In the next post, I will show how to use other models from Hugging Face!

Loading the Selected Model

Using the modelConfiguration instance, we can load our model:

let modelContainer = try await LLMModelFactory.shared.loadContainer(
    configuration: modelConfiguration
) { progress in
    Task { @MainActor in
        self.downloadProgress = progress
    }
}

LLMModelFactory.shared.loadContainer method automatically downloads the model from Hugging Face if it is not available locally. It also handles creating the model with the appropriate architecture and loading the weights from .safetensors files. It also takes a closure to allow us to track the downloading progress.

Creating an Input

To run our model, we need to provide an input:

let result = try await modelContainer.perform { context in
  let prompt = UserInput(prompt: prompt)
  let input = try await context.processor.prepare(input: prompt)  

  /* Generate output */
}

• We call modelContainer.perform, which allows us to interact with the ModelContext.
• We use UserInput to transform the prompt into an input format. UserInput can also include images and videos.
• Finally, we convert the prompt into an LMInput instance using context.processor.prepare, which will be used for generating the output.

Running the LLM Model

To run the model, we use the MLXLMCommon module:

/* Create input */

return try MLXLMCommon.generate(input: input, parameters: .init(), context: context) { tokens in
    let text = context.tokenizer.decode(tokens: tokens)

    Task { @MainActor in
        output = text
    }

    return .more
}

• MLXCommon.generate takes the input and the context from the perform method and generates the output inside the closure.
• The closure receives the encoded tokens, so we first decode them using the tokenizer before using the output.
• Finally, we return .more to continue generating output. If you want to stop generation — for example, when reaching a maximum token limit — you can return .stop instead.

Final Application

You can find the app I developed for this blog post here:

GitHub - ibrahimcetin/MLXSampleApp

Tip: Each blog post also has its own branch to make it easy to find the corresponding code for each part.

Developing on iOS Simulators

When try to run MLX Swift on an iOS simulator, your app will crash because MLX requires a modern Metal MTLGPUFamily and the simulators does not provide that.

The MLX documentation has some recommendations for the development. In summary, they suggests developing the UI on simulator but to be able to run MLX you need to have an actual device.

Increasing Memory Limits for Larger Models

Running larger language models requires more memory, and iOS imposes memory limits on apps by default. If your model exceeds these limits, the app may crash due to insufficient resources.

To prevent this, you need to enable “Increased Memory Limit” in your app’s entitlements:

1. Open your Xcode project.
2. Go to Signing & Capabilities.
3. Click “+ Capability” and search for “Increased Memory Limit”.
4. Add it to your app.

This setting allows your app to use more memory, making it possible to run larger models without crashes.

Conclusion

Running LLMs with MLX Swift is this simple!
For now, running large parameter models is not feasible, but in cases where small models are sufficient, this approach can be useful.

To summarize, we:

• Learned the basics of running LLMs on-device with MLX Swift.
• Used a small model, Llama 3.2 1B 4-bit.
• Prepared inputs and executed inference.

In the next post, we’ll explore how to use custom models!

References

• GitHub - ml-explore/mlx-swift-examples: Examples using MLX Swift
• GitHub - ml-explore/mlx: MLX: An array framework for Apple silicon
• GitHub - ml-explore/mlx-swift: Swift API for MLX
• Exploring MLX Swift: Adding On-Device Inference to your App