Ir para o conteúdo

Instalação

O ort-vision-sdk é distribuído como dois pacotes independentes. Instale o que combina com a sua plataforma — ou os dois, se você compartilha modelos entre o backend Python e o frontend no navegador.

Python (PyPI)

Requer Python 3.11+.

pip install ort-vision-sdk            # somente CPU (padrão)
pip install "ort-vision-sdk[gpu]"     # adiciona onnxruntime-gpu (CUDA / TensorRT)
pip install "ort-vision-sdk[opencv]"  # adiciona o backend de imagem OpenCV
pip install "ort-vision-sdk[compose]" # adiciona onnx, para fundir modelos num pipeline
pip install "ort-vision-sdk[quantize]" # adiciona onnx, para quantizar modelos em INT8
pip install "ort-vision-sdk[dev]"     # ruff, mypy, pytest, build, twine

Dependências base: onnxruntime>=1.17.0, numpy>=1.24.0, pillow>=10.0.0.

Extras

Extra Adiciona Quando usar
gpu onnxruntime-gpu Inferência em GPU NVIDIA via CUDA / TensorRT.
opencv opencv-python Backend de imagem OpenCV (alternativa ao Pillow).
compose onnx Fundir detector + classificador num único .onnx — ver Pipelines fundidos.
dev ruff, mypy, pytest, build, twine Contribuir com o pacote.

compose é só para o build

O onnx (a biblioteca que reescreve o protobuf) é necessário apenas para fundir modelos, um passo que você roda uma vez junto do seu pipeline de export. Rodar o .onnx fundido não precisa de nada além do onnxruntime que já vem na instalação base.

CPU vs. GPU

onnxruntime (CPU) e onnxruntime-gpu não devem coexistir no mesmo ambiente. Para usar GPU, instale o extra gpu em um ambiente limpo (sem o onnxruntime de CPU já presente), ou desinstale-o antes.

GPU disponível ≠ GPU carregável

onnxruntime.get_available_providers() responde "isto foi compilado no wheel", não "isto consegue carregar". O onnxruntime-gpu lista CUDAExecutionProvider sempre, e ainda assim registra CPU quando o loader dinâmico não acha o libcudnn.so.9. O resultado é um deploy que pediu GPU, recebeu CPU sem erro nenhum, e só aparece na conta de latência semanas depois.

O caso é mais escorregadio do que parece: importar torch antes faz o CUDA carregar, porque o wheel do torch traz o cuDNN e o carrega no processo. O mesmo código funciona ou não dependendo da ordem de import de uma biblioteca que o SDK nem depende.

A partir da 0.9.0 o SDK reconcilia isso: session.providers lê de volta o que o ORT registrou, e pedir um provider por nome e não recebê-lo emite um UserWarning em vez de silêncio.

Verificar a instalação

python -c "from ort_vision_sdk import Classifier, Detector, Segmenter; print('OK')"

E, quando a intenção é rodar em GPU, confirme onde ela de fato rodou:

from ort_vision_sdk import OrtSession

session = OrtSession("yolov8n.onnx", providers=["cuda"])

print(session.requested_providers)  # ['CUDAExecutionProvider'] — o que foi pedido
print(session.providers)            # o que o ORT registrou de verdade

Vale para as tasks também

Detector, Classifier e Segmenter constroem um OrtSession por baixo e o expõem em .session, então detector.session.providers responde a mesma pergunta quando você não injetou um backend próprio.

Se a segunda linha imprimir apenas ['CPUExecutionProvider'], o cuDNN não está alcançável — instale-o, ou aponte o LD_LIBRARY_PATH para onde ele está.

Web (npm)

npm install @mauriciobenjamin700/ort-vision-sdk-web onnxruntime-web

onnxruntime-web é uma peer dependency (faixa aceita: >=1.22.0). Você escolhe a versão e distribui os arquivos .wasm correspondentes — o SDK não empacota o runtime para que você controle a versão e o bundle. O SDK exige Node.js 20 ou mais novo onde roda fora do navegador (testes, SSR, build).

Atualizando da 0.11.x: onnxruntime-web >= 1.22 e Node >= 20

A partir da 0.12.0 o peer sobe de >=1.17.0 para >=1.22.0, e o engines de >=18 para >=20.

Por que o ORT: abaixo da 1.22 o onnxruntime-web não informa os shapes de entrada e saída da sessão. As tasks liam o tamanho de entrada e o número de classes de lá e, sem resposta, caíam em silêncio nos defaults (640 para detecção, 224 para classificação): um modelo exportado em outro tamanho quebrava no predict() com Got invalid dimensions for input. Medido na 1.17.3, 1.18.0, 1.19.2, 1.20.1 e 1.21.0.

A 0.12.0 também passou a ler esses shapes do próprio .onnx, então uma versão antiga deixa de quebrar desse jeito — mas é a 1.22 em diante que a suíte de testes roda contra o runtime real, a cada PR.

Por que o Node: o Node 18 está fora de suporte desde abril de 2025.

O que fazer: npm install onnxruntime-web@latest (e sirva os .wasm da mesma versão). Quem já usa 1.22 ou mais novo e Node 20+ não muda nada.

Arquivos .wasm e WebGPU

Para que o WebGPU realmente seja usado (a ordem de providers padrão é ["webgpu", "wasm"]), você precisa de um build recente do ORT-Web, um navegador Chromium com WebGPU habilitado e um contexto seguro (https:// ou localhost). Sem isso, o runtime cai automaticamente para WebAssembly.

Verificar a instalação

node -e "import('@mauriciobenjamin700/ort-vision-sdk-web').then(m => console.log(Object.keys(m)))"

E, no navegador, confirme onde a inferência de fato rodou:

const det = await Detector.create("/models/yolov8n.onnx", {
  providers: ["webgpu"],
});

console.log(det.session.requestedProviders);  // ["webgpu"] — o que foi pedido
console.log(det.session.providers);           // o que este navegador pode oferecer

WebGPU disponível ≠ WebGPU carregável

O ORT-Web não expõe equivalente ao getProviders() do Node: não dá para perguntar em qual provider a sessão acabou. Uma página que pede webgpu num aparelho sem ele roda em WASM várias vezes mais devagar, sem erro nenhum.

A partir da 0.8.0 o SDK estreita a lista pedida pelo que o navegador realmente consegue oferecer (navigator.gpu existir e devolver adapter), e pedir um provider por nome e não conseguir emite console.warn. É best-effort: um provider que sobrevive à checagem ainda pode falhar dentro do ORT por um motivo que o navegador não expõe.

Próximos passos