Skip to content
Closed
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
2 changes: 1 addition & 1 deletion .agents/skills/add-api-tests/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Key helpers:

| Helper | Use |
| :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| `fakeJsi.registerModel(path, program)` | Make `loadModel(path)` succeed with a given schema and `execute` |
| `fakeJsi.registerModel(source, program)` | Make `loadModel(source)` succeed with a given schema and `execute` |
| `fakeJsi.registerTokenizer(path, vocabulary)` | Same for `loadTokenizer` |
| `fakeJsi.registerLLMRunner(path, program)` | Same for `createLLMRunner`: a context window and the responses to generate, one per `generate` call |
| `fakePhonemizer.serve(text, phonemes)` | Script the native grapheme-to-phoneme converter |
Expand Down
11 changes: 11 additions & 0 deletions docs/docs/03-core-and-advanced/02-models-and-tensors.md
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,17 @@ const model = await wrapAsync(loadModel)('/path/to/model.pte', {
});
```

`loadModel()` also accepts an in-memory `ArrayBuffer` or a custom
`ModelDataLoader` (`{ size(): number, load(offset: number, size: number): ArrayBuffer }`),
and an optional `dataMapPath` for models exported with an external `.ptd`
weight archive:

```typescript
const model = await wrapAsync(loadModel)(programBuffer, {
dataMapPath: '/path/to/weights.ptd',
});
```

See [Worklets & Threading](./06-worklets-and-threading.md) for how
[`wrapAsync`](../06-api-reference/functions/wrapAsync.md) and worklet runtimes
fit together.
Expand Down
34 changes: 34 additions & 0 deletions packages/react-native-executorch/__tests__/core/model.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,40 @@ describe('loadModel', () => {
model.dispose();
});

it('loads from an in-memory ArrayBuffer and forwards dataMapPath', () => {
const schema = exported(method('forward', [f32(4)], [f32(4)]));
const modelBuffer = new Uint8Array([1, 2, 3, 4]).buffer;
const weightsBuffer = new Uint8Array([5, 6, 7, 8]).buffer;
fakeJsi.registerModel(modelBuffer, { schema });

const model = loadModel(modelBuffer, { dataMapPath: weightsBuffer });
expect(model.path).toBe('<buffer>');
expect(fakeJsi.modelLoads()).toEqual([
{ source: modelBuffer, options: { dataMapPath: weightsBuffer } },
]);
model.dispose();
});

it('loads from a custom ModelDataLoader and forwards a loader dataMapPath', () => {
const schema = exported(method('forward', [f32(4)], [f32(4)]));
const modelLoader = {
size: () => 4,
load: (_offset: number, size: number) => new ArrayBuffer(size),
};
const weightsLoader = {
size: () => 8,
load: (_offset: number, size: number) => new ArrayBuffer(size),
};
fakeJsi.registerModel(modelLoader, { schema });

const model = loadModel(modelLoader, { dataMapPath: weightsLoader });
expect(model.path).toBe('<loader>');
expect(fakeJsi.modelLoads()).toEqual([
{ source: modelLoader, options: { dataMapPath: weightsLoader } },
]);
model.dispose();
});

it('propagates a load failure as a thrown error', () => {
expect(() => loadModel('/models/missing.pte')).toThrow(/missing.pte/);
});
Expand Down
23 changes: 23 additions & 0 deletions packages/react-native-executorch/__tests__/hooks/useModel.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,29 @@ describe('useModel', () => {
expect(instances).toHaveLength(1);
});

it('rebuilds when an ArrayBuffer inside the config changes identity', async () => {
const instances: Instance[] = [];
const factory = jest.fn(async (config: { id: string; modelPath: ArrayBuffer }) => {
const instance = { dispose: jest.fn(), id: config.id };
instances.push(instance);
return instance;
});
const first = new Uint8Array([1, 2]).buffer;
const second = new Uint8Array([3, 4]).buffer;
const { result, rerender } = await renderHook(
({ config }: { config: { id: string; modelPath: ArrayBuffer } }) => useModel(factory, config),
{ initialProps: { config: { id: 'a', modelPath: first } } }
);
await waitFor(() => expect(result.current.model).toBeDefined());

await rerender({ config: { id: 'a', modelPath: first } });
expect(factory).toHaveBeenCalledTimes(1);

await rerender({ config: { id: 'b', modelPath: second } });
await waitFor(() => expect(result.current.model?.id).toBe('b'));
expect(instances[0]!.dispose).toHaveBeenCalledTimes(1);
});

it('disposes an instance that arrives after unmount', async () => {
const gate = deferred();
const instance = { dispose: jest.fn(), id: 'late' };
Expand Down
38 changes: 29 additions & 9 deletions packages/react-native-executorch/__tests__/support/fakeJsi.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
*/
import { TextDecoder } from 'util';
import type { ConcreteDim, ModelSpec } from '../../src/core/schema';
import type { ModelSource } from '../../src/core/model';
import type { DType } from '../../src/core/tensor';
import { FakeTensor, tensorTracker } from './fakeTensor';
import { cv, fakePhonemizer, llm, math, speech } from './fakeOps';
Expand Down Expand Up @@ -43,9 +44,13 @@ export type FakeProgram = {
execute?: FakeExecute;
};

const programs = new Map<string, FakeProgram>();
const programs = new Map<ModelSource, FakeProgram>();
const liveModels = new Set<string>();
const executions: { path: string; methodName: string }[] = [];
const modelLoads: {
source: ModelSource;
options?: { eagerLoadMethods?: boolean; dataMapPath?: ModelSource };
}[] = [];

class FakeModel {
readonly path: string;
Expand Down Expand Up @@ -227,12 +232,18 @@ const jsi = {

createTensor: (shape: number[], dtype: DType) => new FakeTensor(dtype, shape),

loadModel: (path: string, _options?: { eagerLoadMethods?: boolean }) => {
const program = programs.get(path);
loadModel: (
source: ModelSource,
options?: { eagerLoadMethods?: boolean; dataMapPath?: ModelSource }
) => {
const program = programs.get(source);
const label =
typeof source === 'string' ? source : source instanceof ArrayBuffer ? '<buffer>' : '<loader>';
if (!program) {
throw new Error(`loadModel: no program registered at '${path}' (register one via fakeJsi)`);
throw new Error(`loadModel: no program registered at '${label}' (register one via fakeJsi)`);
}
return new FakeModel(path, program);
modelLoads.push({ source, options });
return new FakeModel(label, program);
},

getExecuTorchRegisteredBackends: () => [...registeredBackends],
Expand Down Expand Up @@ -266,12 +277,12 @@ export function installFakeJsi(): void {

export const fakeJsi = {
/**
* Makes `loadModel(path)` succeed and return `program`.
* @param path The model path a pipeline will be pointed at.
* Makes `loadModel(source)` succeed and return `program`.
* @param source The model path or buffer a pipeline will be pointed at.
* @param program The schema, backends and `execute` behavior to serve.
*/
registerModel(path: string, program: FakeProgram): void {
programs.set(path, program);
registerModel(source: ModelSource, program: FakeProgram): void {
programs.set(source, program);
},

/**
Expand Down Expand Up @@ -309,6 +320,14 @@ export const fakeJsi = {
return executions;
},

/** @returns Every `loadModel` call made so far, in order. */
modelLoads(): readonly {
source: ModelSource;
options?: { eagerLoadMethods?: boolean; dataMapPath?: ModelSource };
}[] {
return modelLoads;
},

/** @returns Paths of models that were loaded and not disposed. */
liveModels(): string[] {
return [...liveModels].sort();
Expand Down Expand Up @@ -336,6 +355,7 @@ export const fakeJsi = {
liveModels.clear();
liveTokenizers.clear();
executions.length = 0;
modelLoads.length = 0;
registeredBackends = ['XnnpackBackend', 'CoreMLBackend'];
jsi.isEmulator = false;
fakePhonemizer.reset();
Expand Down
38 changes: 38 additions & 0 deletions packages/react-native-executorch/__tests__/tasks/llmRunner.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -888,3 +888,41 @@ describe('createLLMMultimodalRunner — audio input', () => {
}
});
});

describe('createLLMRunner — in-memory and external weights', () => {
it('loads from an ArrayBuffer and forwards dataMapPath', async () => {
const modelBuffer = new Uint8Array([1, 2, 3, 4]).buffer;
const weightsBuffer = new Uint8Array([5, 6, 7, 8]).buffer;
fakeJsi.registerModel(modelBuffer, {
schema: TEXT_SPEC,
execute: (methodName) => {
switch (methodName) {
case 'get_max_seq_len':
return [128];
case 'get_max_context_len':
return [512];
case 'get_vocab_size':
return [100];
case 'use_kv_cache':
case 'enable_dynamic_shape':
return [true];
case 'get_eos_ids':
return [1];
default:
return undefined;
}
},
});

const runner = tracked(
await createLLMRunner(modelBuffer, TOKENIZER_PATH, undefined, undefined, {
dataMapPath: weightsBuffer,
})
);

expect(runner.modelPath).toBe('<buffer>');
expect(fakeJsi.modelLoads()).toEqual([
{ source: modelBuffer, options: { dataMapPath: weightsBuffer } },
]);
});
});
Loading