An on-device model can fail in two very different ways. It can produce the wrong values after conversion, or it can produce acceptable values too slowly for the feature that needs them. Treating both problems as an app bug wastes time. The useful question is where the failure first becomes observable: in the converted model graph, while the app loads a model, or during an inference loop on the device.
Core AI provides three tools for those layers. Core AI Debugger works directly with a model asset. The Core AI debug gauge shows live model activity during an Xcode debug session. The Core AI instrument records runtime timing across the CPU, GPU, and Neural Engine. Use them in that order of depth rather than opening every tool for every symptom.
Start with the smallest observable failure
Write down one reproducing input and the expected property of its output. It might be a classification label, an embedding similarity, an image mask, or a numerical tolerance against a PyTorch reference. If the output is already wrong for that fixed input, begin with the asset and Core AI Debugger. If it is correct but feels delayed in the running feature, begin with the gauge or Instruments.
This distinction prevents a common detour: trying to tune compute units or UI scheduling when the converted graph is numerically wrong, or inspecting every intermediate tensor when the only issue is first-load specialization.
Use Core AI Debugger to locate divergence
Core AI Debugger visualizes an .aimodel operation graph, runs it, and lets you inspect intermediate tensor values. It can compare a converted run with a reference run, then identify sync points where values no longer match. This is the fastest path from "the final output changed" to a specific operation or Python source area worth investigating.
The source mapping depends on debug metadata included during export. Preserve that metadata for development assets. Without it, the graph is still useful, but the route back to the PyTorch module that produced an operation becomes slower and more error-prone.
Use a reference case that is small enough to inspect. A complete production conversation or large image can make every tensor difficult to reason about. Once the model matches for focused cases, expand the validation set to the real input ranges.
Use the Xcode gauge to separate lifecycle delays
The Core AI debug gauge shows model load, specialization, and inference activity while the app runs under Xcode. It is the quickest way to determine whether a delay is happening before the model can serve work or during the work itself.
For example, a noticeable first-use delay followed by quick later calls points toward specialization or cache behavior. A delay on every request points toward inference, input preparation, or the surrounding application pipeline. That difference decides whether to prepare the asset earlier, compile ahead of time, or profile the inference loop.
The gauge is a diagnostic signal, not a benchmark. Use it to select the next tool and the time range worth measuring.
Record an interaction with Core AI Instruments
Use the Core AI instrument when an app experience is repeatedly slow or becomes slower over time. Record the exact interaction, then inspect the duration and sequence of inference intervals. A transformer loop whose intervals increase as history grows often needs an architectural change such as stateful key-value caching. A single, consistently expensive call may need a smaller model, different input preparation, or a closer look at model layout.
Core AI Instruments spans CPU, GPU, and Neural Engine execution. It gives you a model-level timing view, but the surrounding app still matters. Pair the trace with the Swift call site and UI interaction so an inference improvement does not simply move visible work somewhere else on the main actor.
Close the loop with a repeatable comparison
After every fix, run the same reference input or recorded interaction again. For a numerical fix, verify the same tolerance and expected output. For a performance fix, compare the same sequence length, device class, and workload. A faster first inference is not enough if the long-running path still degrades.
Keep the reference inputs and traces with the model project when possible. Model changes, conversion updates, and platform updates all deserve the same evidence as an application code change.
Key takeaway
Core AI debugging is a layered workflow. Use the debugger to prove correctness, the Xcode gauge to identify lifecycle stages, and Instruments to measure runtime cost. Each tool answers a different question, and using the right one early keeps model work concrete.