GPU controls and tuning

SoAI exposes a GPU slider only when the current GPU, driver, and vendor backend report that control as actionable. Monitoring remains available when a device has no supported hardware changes.

For manual control in the SoAI WebUI, open Hardware and change a setting yourself. The same power, clock, and fan settings are also reachable by a model through the hardware agent tools, described in Hardware tools. See Let a model apply the settings below for when to choose which.

Control availability and measurement

Open Hardware from the side navigation. The page itself requires Hardware read access (HARDWARE_READ). The GPU control section appears only to an Administrator with GPU tuning (HW_GPU_TUNING). If no detected GPU reports an actionable control, the section shows No GPU controls available. Standard users cannot receive that permission.

A panel can offer Power limit, Core clock offset, Memory clock offset, or Fan speed. Each slider appears separately, so an absent control is unavailable for that GPU in its current host state.

The global SYSTEM.RUNTIME.HARDWARE_MUTATION_DISABLED setting prevents hardware mutations. SoAI rejects mutation requests while it is enabled. An Administrator with Configuration changes (CONFIG_PATCH) can select the Settings button at the right of the header, then select Settings from its menu. Select Advanced in the page header and search for the complete configuration path. Set Hardware mutation disabled to Off, then select Save.

What a slider does depends on the vendor backend behind it. An NVIDIA card takes a power limit in watts and clock offsets in MHz through NVML, while AMD applies power and fan through amd-smi and reaches clocks through performance levels or the AMDGPU OverDrive files, so a raw MHz offset is not always what you get. Intel exposes a power limit and a clamped core-clock range through xpu-smi and has no fan or memory clock control at all. The AMD and Intel paths act on host interfaces that need elevated privileges, so a control can be listed and still fail because the host refuses the change. SoAI clamps a requested value into the range the device reports, and a change the backend cannot perform comes back as an explicit failure rather than a silent no-op.

Measure before tuning

  1. In Hardware > Chart, select the GPU and the metrics that matter to the workload, such as utilization, temperature, power draw, and memory use.
  2. Run the model with the same prompt shape and concurrency you intend to compare later.
  3. Record the result before changing a hardware setting.

There is no universally safe or faster power, clock, or fan value. Driver limits, cooling, GPU firmware, model size, backend, and workload all affect the result. Keep only a change that improves the workload you measured without exceeding the operating limits of the hardware.

Risk, warranty, and where to start

The GPU control panel carries a standing warning that incorrect settings may damage your GPU, and it is meant literally. Raising clocks moves the card outside the operating point its manufacturer validated, and the cost is paid in heat, current, and stability: crashes and driver resets are the visible failures, while accelerated wear is the one you notice a year later. Warranty terms differ by vendor and by board partner, and some cover tuning done with the vendor's own utility while others do not, with the AMD warranty excluding damage caused by overclocking even when AMD hardware or software performed it. Read the terms that came with your card before you raise anything, and treat a dead card as a real possible cost of the experiment rather than a remote one.

Lowering the power limit is the opposite trade, and it is the one most local inference hosts actually want. Token generation is usually limited by memory bandwidth rather than by core clock, so a card held under its stock power ceiling keeps most of its throughput while drawing noticeably less: published measurements on machine-learning hosts put a cut of 10% to 20% at roughly 95% of full performance, and deeper cuts on high-end consumer cards trade a few percent of tokens per second for a large drop in watts. The result is a cooler, quieter card, less thermal cycling over a long run, and less strain on the host power supply and the circuit it is plugged into, which is why multi-GPU builds are often configured this way on purpose instead of as a fallback. Sustained heat is the main thing that ages a card running inference for hours at a time, so a lower ceiling is a longevity argument as much as an electricity one. When a control offers Auto, selecting it restores the default behavior reported by the driver.

Memory clock deserves its own caution. GPU memory errors do not announce themselves: the card corrects or replays what it can and passes the rest through, so a memory overclock that looks stable in a game surfaces in inference as wrong output rather than as a crash. Raise it in small steps if you raise it at all, keep a prompt whose good answer you already know, and back off at the first inconsistent result instead of waiting for a visible artifact.

The rest is ordinary discipline. Change one control at a time so a failure has one candidate cause, move in small increments, and rerun the same workload after each change, because a setting that helps one measurement can hurt another. Instability from clocks often appears only once the card has been hot for a while, so a long run tells you more than a short one, and it is worth writing down the last setting that survived it. Manual fan speed is the quiet exception in this list: fixing a percentage removes the driver's own temperature response, and a value that is comfortable at idle can be far too low an hour into a sustained load.

Apply, test, and save settings

  1. Find the GPU's GPU control panel.
  2. For a supported setting, turn off Auto and set a value within the displayed range.
  3. Select Apply.
  4. Use the live telemetry and Chart to check the result before changing another control.

An AMDGPU OverDrive clock slider accepts frequencies throughout its displayed range. Arrow keys move by the displayed step rather than jumping between the configured endpoints. Some drivers expose manual clock changes without a readable default frequency. For those controls, Auto and Reset are unavailable; record the original frequency before applying a change so you can restore it manually.

Reset restores supported controls to Auto and clears unsaved slider edits. Saved settings slots remain available. Controls without a readable reset target require manual restoration, as described above.

Test the result

SoAI Bench needs a working OpenCL driver, support for a 256 MiB allocation, and enough device memory for the workload. Integrated GPUs can use shared memory. A device labeled Custom can run when it meets these requirements and SoAI can identify it. If preflight fails, read its reason, update the driver if needed, and refresh hardware detection.

Integrated and discrete GPUs use the same benchmark profiles and scoring rules, including the 256 MiB memory workload. Existing scores remain in History without recalculation.

  1. For a certified run, select SoAI Bench at the top of the Hardware page, select the GPU, then select Start.
  2. For a stress run after applying a setting, select Test then Stress in the GPU controls panel.
  3. Watch temperature, power, and status while it runs, and select Stop to end a stress run early.
  4. After a run exists, use the History control in the GPU panel to compare or export previous results.

A stress run started from this page lasts at most 60 seconds and ends on its own, so Stop only shortens it. The page continues to show live hardware data during a run. The hardware_benchmark tool accepts a temperature_limit_celsius checkpoint for either profile. Readings above that limit stop the run after the active OpenCL phase. The benchmark controls report an explicit unsupported result when the selected GPU or runtime cannot run the requested profile.

Each standard workload phase has a 3,600-second execution limit; the preliminary capability check keeps its 60-second limit. A timeout identifies the affected operation and limit, and the run fails without a score. Check that the graphics driver responds before retrying. You can stop a run while a workload is still executing.

While a certified SoAI Bench run is active on a GPU, SoAI blocks saving or applying its pending settings. Stop the run or wait for it to finish before saving. If benchmark status is unknown, check its status before trying again.

Save and reuse a slot

Saved settings follow the physical GPU, including accepted alternate identifiers. Cards with the same model name keep separate settings. When alternate identifiers contain different saved profiles, SoAI consolidates them into the 3 available slots and retains the original profiles in the saved GPU data. Consolidation preserves a copy of the original saved file and does not apply settings to the GPU.

  1. Apply and test a manual setting.
  2. Select Save, then select slot 1, 2, or 3.
  3. To reuse a saved setting, select its filled slot to preview it, then select Apply.
  4. With a saved slot selected, choose Apply at boot and select Apply to make that slot the startup profile.

If the original startup preferences disagree, automatic application is disabled until you review a saved slot and enable Apply at boot again. Ambiguous device identity or unreadable saved data still requires attention before GPU changes can proceed.

Apply at boot is shown only while a saved slot is selected, and saving new values into a slot replaces that slot's settings. The boot flag survives a clean restart but deliberately does not survive a crash: when SoAI starts after an unclean shutdown it clears Apply at boot on every saved device, so a profile that may have contributed to the hang is not reapplied on the way back up. Re-enable it once you are satisfied the host is stable, and recheck a saved profile after a GPU or driver change before relying on it at startup.

After an unsafe shutdown, SoAI restores recorded settings or supported defaults. Controls without a readable reset target need manual restoration. If SoAI cannot identify the GPU or verify a safe reset target, changes remain restricted; review the reported recovery cause. Startup also verifies the core database before serving requests. This can take minutes and should not be interrupted. See After an unclean shutdown before tuning again.

An out-of-range setting reports the field, requested value, supported bounds, and unit. Choose a value within the reported range for the selected physical GPU. If saving succeeds but a live observation fails, the saved profile remains durable while live state is marked stale and refreshed.

Let a model apply the settings

An agent reaches the same controls through three tools. hardware_snapshot reads the sensors and reports the GPU device IDs, hardware_control lists the supported controls for a card and applies power, fan, and clock values, and hardware_benchmark runs a stress or SoAI Bench workload to check the result. Hardware tools covers their arguments and the order to use them in.

A conversation needs a model that supports tool calling, the MCP usage (MCP_USE) permission, and the tools selected in Chat configuration > Tools. hardware_control and hardware_benchmark also require an administrator and Execute mode, and they refuse to run outside a live agent turn that selected them. Chat and Plan mode cannot reach them at all.

Those two tools are internal to SoAI. They belong to the administrator catalog only, so they never appear in the tool list that MCP server mode publishes. Third-party software that uses SoAI as an MCP server can call hardware_snapshot but cannot change or stress a GPU. Model-orchestrated GPU control happens inside a SoAI conversation or not at all.

Use this page for a one-off change you want to see and confirm yourself, including saved slots and Apply at boot, which the tools do not manage. Use the tools when a reading should lead to a change and a follow-up benchmark without you driving each step. Leave Require tool approval on for any conversation that can reach them, so you still see the exact settings before SoAI applies them.

Related documentation