Test a Gyoza Op#

You have built your op and the image is ready. Before deploying it to a cluster, you need to verify that it actually works, that the inputs are validated, the function runs correctly, and the output is what you expect.

Gyoza gives you two ways of testing your op:

  1. gyoza run: Allows you to test your op with the Gyoza IO schema, directly in the current Python process. Its faster and is recommended for the tests during the development of your op.

  2. gyoza run-container: Allows you to test the op as an already built Docker image, reproducing the exact conditions of production. Its naturally slower and is recommended for the “final” tests before deploying your op.

Prerequisites#

We will use the same sample op from Build a Gyoza Op throughout this guide:

from pydantic import BaseModel
from gyoza import gyoza_op


class Input(BaseModel):
    image_path: str
    top_k: int = 3


class Output(BaseModel):
    label: str
    confidence: float


@gyoza_op(input_model=Input, output_model=Output)
def classify_image(image_path: str, top_k: int = 3):
    # ... load model, run inference ...
    return "cat", 0.97

Testing your op with gyoza run#

gyoza run loads your Python file directly in the current process, validates the inputs against the op’s Input model, calls the decorated function, and writes the result to a JSON file. This allows you to test your op with the Gyoza IO schema fast, but requires you to have gyoza and all the dependencies of your op installed in your current environment.

There are two ways to pass input to gyoza run:

Inline: Pass the JSON payload directly on the command line:

gyoza run --file main.py \
    --inline-input '{"image_path": "cat.jpg", "top_k": 3}' \
    --output ./output.json

File: Point to a JSON file on disk:

gyoza run --file main.py \
    --input ./input.json \
    --output ./output.json

Note

In both cases, you should specify the output file path with --output <path>. Otherwise, the output will be written to the default output file path, which is /data/output.json.

Both produce the same result. After the run you can inspect the output:

cat ./output.json

{
  "label": "cat",
  "confidence": 0.97
}

By default gyoza auto-detects the first @gyoza_op function in the file. If the file contains more than one, use --function <name> to pick one.

See also

You can find the full gyoza run command reference in CLI Reference.

Testing your op container with gyoza run-container#

Once you are happy with the logic, it is time to verify that everything works inside the actual Docker image, the same image that will run in production.

gyoza run-container wraps docker run so you don’t have to write it by hand. It automatically sends your local input into the container and, once the op finishes, copies the container’s output back to your provided local output file.

Before using this command, make sure the image is built:

gyoza build ./my-op

The input/output interface is the same as gyoza run:

Inline:

gyoza run-container myregistry/sample-op:1.0.0 \
    --inline-input '{"image_path": "cat.jpg", "top_k": 3}' \
    --output ./output.json

File:

gyoza run-container myregistry/sample-op:1.0.0 \
    --input ./input.json \
    --output ./output.json

The host file is mounted read-only at /data/input.json inside the container, and the output is copied back to the host path you specified.

Automatic path mapping#

Normally, when a container needs to receive local files as input you have to manually mount volumes with docker run -v. The gyoza run-container command handles this for you, it analyses every value in your input JSON and, if it detects a valid local file or directory, it automatically bind-mounts it into the container and rewrites the path so your op can read it directly.

# /images/cat.jpg exists locally, gyoza mounts it automatically
gyoza run-container myregistry/sample-op:1.0.0 \
    --inline-input '{"image_path": "/images/cat.jpg", "top_k": 3}' \
    --output ./output.json

If you need to disable this behaviour (e.g. the path already refers to a location inside the container image), pass the --no-map-paths flag on your command.

gyoza run-container myregistry/sample-op:1.0.0 \
    --inline-input '{"image_path": "/images/cat.jpg", "top_k": 3}' \
    --output ./output.json \
    --no-map-paths

Forwarding extra arguments to docker run#

Since gyoza run-container is a docker run wrapper, you can pass any compatible docker run argument after --, for example to enable GPU access, adjust resources, or set environment variables:

# GPU support
gyoza run-container myregistry/sample-op:1.0.0 \
    --input ./input.json \
    --output ./output.json \
    -- --gpus all

# Custom network and environment variable
gyoza run-container myregistry/sample-op:1.0.0 \
    --input ./input.json \
    --output ./output.json \
    -- --network host -e CUSTOM_VAR=value

# Combine multiple flags
gyoza run-container myregistry/sample-op:1.0.0 \
    --input ./input.json \
    --output ./output.json \
    -- --gpus all --memory 8g --cpus 4

See also

Full option reference in CLI Reference.

Next steps#

  • Deploy a Gyoza Op: Push the image, register the OpDefinition on the server, and start running your op in the cluster.