Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,20 @@ All VAD engines use the same bundled model and streaming API.
The compatibility fallbacks apply to VAD.
Decision-model inference currently requires the Akiki engine and a supported export.

Automatic library discovery checks only the package's `native` directory.
It does not search developer directories, Cargo outputs, or the current directory.
For a separately built library, pass `library_path=` in Python or `--library-path`
on the command line. You can also set an engine-specific environment variable:

| Library | Environment variable |
| --- | --- |
| VAD | `AKIKI_VAD_LIBRARY` |
| Decision models (current MiniLM/BERT runtime) | `AKIKI_MINILM_LIBRARY` |

An explicit path takes priority over the environment variable and bundled library.
If the selected library is missing or incompatible, no other library is tried.
VAD with `Engine.AUTO` can still use the ONNX, then PyTorch compatibility fallbacks.

### Model precision

`VAD()` and the command line use INT8 by default when running the Akiki engine.
Expand Down
12 changes: 12 additions & 0 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,18 @@ requires both on x86_64 and ARM64. Linux wheel architecture is
derived from the ELF libraries, so cross-built ARM64 libraries cannot be
accidentally labelled as x86_64.

The build helper does not install the libraries into the Python package.
To test a source checkout with these Linux builds, set both runtime paths:

```bash
export AKIKI_VAD_LIBRARY="$native/libakiki_vad_engine.so"
export AKIKI_MINILM_LIBRARY="$native/libakiki_minilm_engine.so"
```

Runtime discovery checks only the package's `native` directory when no path is set.
It does not use `AKIKI_INFERENCE_DIR`, Cargo variables, or developer build directories.
Use the library filenames for your target system with Windows or macOS builds.

## Build the Linux ARM64 wheel

The wheel includes VAD and the current MiniLM/BERT decision runtime.
Expand Down
22 changes: 2 additions & 20 deletions src/akiki/_engines.py
Original file line number Diff line number Diff line change
Expand Up @@ -141,30 +141,12 @@ def library_name(stem="akiki_vad_engine"):


def library_candidates(library_path=None, stem="akiki_vad_engine", variable="AKIKI_VAD_LIBRARY"):
"""Use an explicit library or the library in the package."""
explicit = library_path or os.environ.get(variable)
if explicit:
yield Path(explicit).expanduser()
return
name = library_name(stem)
yield Path(__file__).parent / "native" / name
# The offline build helper keeps artifacts inside the Python workspace.
source_root = Path(__file__).resolve().parents[2]
yield source_root / ".cache/native-target/release" / name
target_dir = os.environ.get("CARGO_TARGET_DIR")
roots = [
Path.home() / "projects/Akiki/akiki-inference",
Path("/projects/Akiki/akiki-inference"),
]
if os.environ.get("AKIKI_INFERENCE_DIR"):
roots.insert(0, Path(os.environ["AKIKI_INFERENCE_DIR"]).expanduser())
targets = ([Path(target_dir).expanduser()] if target_dir else []) + [
r / "target" for r in roots
]
for target in targets:
if os.environ.get("CARGO_BUILD_TARGET"):
target = target / os.environ["CARGO_BUILD_TARGET"]
for profile in ("release", "debug"):
yield target / profile / name
yield Path(__file__).resolve().parent / "native" / library_name(stem)


class AkikiBackend(Backend):
Expand Down
6 changes: 4 additions & 2 deletions src/akiki/decision.py
Original file line number Diff line number Diff line change
Expand Up @@ -307,7 +307,8 @@ def __init__(
available CPUs when loading each specialist. ``model_precision`` requires
this module's enum and defaults to ``ModelPrecision.INT8``.
``library_path`` selects an existing native MiniLM shared library.
It overrides ``AKIKI_MINILM_LIBRARY`` and automatic library discovery.
It overrides ``AKIKI_MINILM_LIBRARY`` and the bundled library.
Automatic discovery does not search developer directories.

Native loading occurs on the first inference or tokenization call.
Use a context manager or ``close()`` to release the loaded models.
Expand Down Expand Up @@ -774,7 +775,8 @@ def __init__(
Passing ``None`` keeps the variant's configured chunk length.
library_path : str or os.PathLike, optional
Path to a specific Akiki MiniLM shared library. Overrides
``AKIKI_MINILM_LIBRARY`` and automatic discovery.
``AKIKI_MINILM_LIBRARY`` and the bundled library.
Automatic discovery does not search developer directories.

Raises
------
Expand Down
4 changes: 2 additions & 2 deletions src/akiki/vad.py
Original file line number Diff line number Diff line change
Expand Up @@ -176,8 +176,8 @@ def __init__(
Pass an ``Engine`` member, such as ``Engine.AKIKI``.
library_path : str or pathlib.Path, optional
Specific local Akiki shared library to load. Affects only the Akiki
engine. If omitted, use ``AKIKI_VAD_LIBRARY`` or discover a bundled
or locally built library.
engine. If omitted, use ``AKIKI_VAD_LIBRARY`` or the bundled library.
Automatic discovery does not search developer directories.
model_precision : ModelPrecision, optional
One of ``ModelPrecision.FP32``, ``FP16``, ``BF16``, ``INT8``,
``INT4``, or ``INT8_FP32_INPUT``. If omitted, Akiki uses INT8 and
Expand Down
123 changes: 123 additions & 0 deletions tests/test_library_discovery.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
"""Load native engines from the package or an explicit local path."""

from pathlib import Path

import pytest

from akiki import _engines, decision
from akiki.vad import VAD, Engine, ModelPrecision


@pytest.fixture(params=["win32", "darwin", "linux"])
def native_library(request, tmp_path, monkeypatch):
monkeypatch.setattr(_engines.sys, "platform", request.param)
monkeypatch.setattr(_engines, "__file__", str(tmp_path / "site-packages/akiki/_engines.py"))
for variable in ("AKIKI_VAD_LIBRARY", "AKIKI_MINILM_LIBRARY"):
monkeypatch.delenv(variable, raising=False)
home = tmp_path / "home"
monkeypatch.setenv("HOME", str(home))
monkeypatch.setenv("USERPROFILE", str(home))
monkeypatch.setenv("AKIKI_INFERENCE_DIR", str(tmp_path / "inference"))
monkeypatch.setenv("CARGO_TARGET_DIR", str(tmp_path / "cargo"))
monkeypatch.setenv("CARGO_BUILD_TARGET", "target-triple")
monkeypatch.chdir(tmp_path)
return (tmp_path / "site-packages/akiki/native").resolve()


@pytest.fixture(
params=[
("akiki_vad_engine", "AKIKI_VAD_LIBRARY"),
("akiki_minilm_engine", "AKIKI_MINILM_LIBRARY"),
]
)
def engine_library(request, native_library, tmp_path):
stem, variable = request.param
name = _engines.library_name(stem)
# Existing developer outputs must not become runtime candidates.
for directory in (
tmp_path,
tmp_path / ".cache/native-target/release",
tmp_path / "home/projects/Akiki/akiki-inference/target/target-triple/release",
tmp_path / "inference/target/target-triple/release",
tmp_path / "cargo/target-triple/release",
tmp_path / "cargo/target-triple/debug",
):
directory.mkdir(parents=True, exist_ok=True)
(directory / name).write_bytes(b"developer library")
return stem, variable, native_library / name


def test_automatic_search_checks_only_the_package(engine_library):
stem, variable, bundled = engine_library
assert list(_engines.library_candidates(stem=stem, variable=variable)) == [bundled]


def test_explicit_path_precedes_environment_and_package(engine_library, tmp_path, monkeypatch):
stem, variable, bundled = engine_library
environment = tmp_path / "environment library" / bundled.name
monkeypatch.setenv(variable, str(environment))
assert list(_engines.library_candidates(stem=stem, variable=variable)) == [environment]

explicit = tmp_path / "explicit library" / bundled.name
for path in (explicit, str(explicit)):
assert list(_engines.library_candidates(path, stem, variable)) == [explicit]

home_library = Path.home() / "local library" / bundled.name
relative = Path("~/local library") / bundled.name
assert list(_engines.library_candidates(relative, stem, variable)) == [home_library]
monkeypatch.setenv(variable, str(relative))
assert list(_engines.library_candidates(stem=stem, variable=variable)) == [home_library]


def load_engine(stem, library_path=None):
if stem == "akiki_vad_engine":
return VAD(
engine=Engine.AKIKI,
model_precision=ModelPrecision.FP32,
library_path=library_path,
)
return decision._load_library(library_path)


@pytest.mark.parametrize("present", [False, True])
def test_consumers_do_not_load_developer_libraries(engine_library, monkeypatch, present):
stem, variable, bundled = engine_library
if present:
bundled.parent.mkdir(parents=True)
bundled.write_bytes(b"incompatible bundled library")
attempts = []

def load(path):
attempts.append(Path(path))
raise OSError("incompatible library")

monkeypatch.setattr(_engines.ctypes, "CDLL", load)
with pytest.raises(RuntimeError, match="No compatible Akiki"):
load_engine(stem)
assert attempts == ([bundled] if present else [])


@pytest.mark.parametrize("present", [False, True])
def test_failed_override_does_not_load_another_library(
engine_library, tmp_path, monkeypatch, present
):
stem, variable, bundled = engine_library
bundled.parent.mkdir(parents=True)
bundled.write_bytes(b"bundled library")
explicit = tmp_path / "custom" / bundled.name
if present:
explicit.parent.mkdir()
explicit.write_bytes(b"incompatible explicit library")
attempts = []

def load(path):
attempts.append(Path(path))
raise OSError("incompatible library")

monkeypatch.setattr(_engines.ctypes, "CDLL", load)
for library_path in (explicit, None):
attempts.clear()
monkeypatch.setenv(variable, str(explicit if library_path is None else bundled))
with pytest.raises(RuntimeError, match=variable):
load_engine(stem, library_path)
assert attempts == ([explicit.resolve()] if present else [])
Loading