feat: add GPU/XPU support to fastembed rankers via model_kwargs

[chinyixiang]

Related Issues

• None

Proposed Changes:

The fastembed library supports GPU acceleration through its providers, cuda, and device_ids
constructor arguments (backed by ONNX Runtime execution providers). Previously, only the four
embedder components exposed this via model_kwargs. The two ranker components —
FastembedRanker and FastembedLateInteractionRanker — were hardcoded to the CPU path with no
way to opt into GPU execution.

This PR is to enable gpu execution path for both FastembedRanker and FastembedLateInteractionRanker

FastembedRanker and FastembedLateInteractionRanker (integrations/fastembed/src/.../rankers/):

• Added model_kwargs: dict[str, Any] | None = None parameter to __init__
• Stored as self.model_kwargs, serialized in to_dict, deserialized via the existing default_from_dict path
• Spread as **model_kwargs into the underlying TextCrossEncoder / LateInteractionTextEmbedding
  constructor in warm_up(), enabling any ONNX Runtime execution provider

FastembedTextEmbedder and FastembedDocumentEmbedder (integrations/fastembed/src/.../embedders/):

• Updated :param model_kwargs: docstring to mention OpenVINOExecutionProvider alongside CUDAExecutionProvider (upstream only documented CUDA)
• Added a "Running on GPU" code block to the class-level docstring showing both paths

Users can now select the execution backend at component construction time:

# NVIDIA GPU — requires onnxruntime-gpu
FastembedRanker(model_name="...", model_kwargs={"providers": ["CUDAExecutionProvider"]})
FastembedTextEmbedder(model="...", model_kwargs={"providers": ["CUDAExecutionProvider"]})

# Intel GPU / XPU — requires onnxruntime-openvino
FastembedRanker(model_name="...", model_kwargs={"providers": ["OpenVINOExecutionProvider"]})
FastembedTextEmbedder(model="...", model_kwargs={"providers": ["OpenVINOExecutionProvider"]})

# CPU (default — no change needed)
FastembedRanker(model_name="...")

The providers key is the recommended path. The fastembed library also accepts cuda=True /
device_ids=[0, 1] as shorthand for single- or multi-GPU CUDA setups; these work through
model_kwargs as well.

How did you test it?

• hatch run fmt — all checks passed, 23 files unchanged
• hatch run test:types — no issues found in 10 source files
• hatch run test:unit — 84 passed, 10 deselected (integration tests, expected)

New unit tests added for both rankers:

• test_init_with_model_kwargs_parameters — verifies the param is stored correctly
• test_to_dict_with_custom_init_parameters — verifies model_kwargs round-trips through serialization
• test_from_dict_with_custom_init_parameters — verifies deserialization restores model_kwargs
• test_warm_up_forwards_model_kwargs — verifies model_kwargs is actually unpacked and passed to
  the underlying fastembed model constructor (the key correctness test)

Notes for the reviewer

• The model_kwargs pattern is identical to what the four embedder components already use —
  this change extends it to the two rankers that were missing it.
• The sparse embedders (FastembedSparseTextEmbedder, FastembedSparseDocumentEmbedder) also
  expose model_kwargs but for BM25 tuning parameters (k, b, avg_len, language), not
  execution providers — those were intentionally left untouched.
• The pre-existing mypy false positive on from fastembed import LateInteractionTextEmbedding
  (fastembed re-exports it dynamically) is not introduced by this PR — it exists on the unchanged
  upstream file and is confirmed to work at runtime.

Checklist

• I have read the contributors guidelines and the code of conduct
• I have updated the related issue with new insights and changes - no related issues
• I added unit tests and updated the docstrings
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test:.

[CLAassistant]

All committers have signed the CLA.

[github-actions]

Heads-up for maintainers

This PR is from a fork and touches integrations whose integration tests require API keys.
Those tests are skipped in CI because fork PRs don't have access to repo secrets for security reasons.

Affected integrations:

• fastembed

Please run the integration tests locally (hatch run test:integration inside each folder) before approving.

[github-actions]

Coverage report (fastembed)

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
integrations/fastembed/src/haystack_integrations/components/embedders/fastembed
fastembed_document_embedder.py
fastembed_text_embedder.py
integrations/fastembed/src/haystack_integrations/components/rankers/fastembed
late_interaction_ranker.py
ranker.py
Project Total

This report was generated by python-coverage-comment-action