espnet3.utils.writer_utils.write_artifact

source

espnet3.utils.writer_utils.write_artifact(value: Any, output_path: Path, field_config: dict | DictConfig | None = None) → Path

Write a single inference artifact to disk and return its path.

This function implements the artifact serialization rules used by espnet3.systems.base.inference.infer() for non-scalar outputs.

Default serialization rules:

1. dict values are saved as JSON. Nested lists inside the dict are preserved through JSON serialization.

   Example:

   write_artifact(
       {"speaker": "spk1", "segments": [1, 3, 8]},
       Path("infer/test-clean/meta/utt1"),
   )

   Result:

   infer/test-clean/meta/utt1.json

2. numpy.ndarray values are saved as .npy by default.

   Example:

   write_artifact(
       np.asarray([[1.0, 2.0]]),
       Path("infer/test-clean/posterior/utt1"),
   )

   Result:

   infer/test-clean/posterior/utt1.npy

3. CPU torch.Tensor values are converted to NumPy and saved as .npy by default.

4. Unknown Python objects are saved with pickle by default.

   Example:

   write_artifact(
       some_python_object,
       Path("infer/test-clean/debug_obj/utt1"),
   )

   Result:

   infer/test-clean/debug_obj/utt1.pkl

5. WAV output is configured explicitly through field_config. The input value is still a normal NumPy array (or CPU tensor); the writer configuration decides that it should be serialized as .wav.

   Example:

   write_artifact(
       waveform_numpy,
       Path("infer/test-clean/audio/utt1"),
       field_config={"type": "wav", "sample_rate": 16000},
   )

   Result:

   infer/test-clean/audio/utt1.wav

6. Custom serialization can be configured through field_config using a function writer.

   Example config:

   field_config = {
       "writer": {
           "_target_": "mypkg.inference.write_custom_artifact",
           "some_option": 123,
       }
   }

   Expected writer signature:

   def write_custom_artifact(value, output_path, some_option=123):
       ...
       return output_path

   The custom writer must be a function. It must return the written file path, and that path must already exist when returned.

Unsupported values:

• Bare top-level list / tuple values are not supported by the inference entrypoint. If structured content is needed, wrap it in a dict and let it be saved as JSON.
• CUDA tensors are rejected. Move them to CPU before writing.

• Parameters:
  • value – Artifact value to serialize.
  • output_path – Base output path. The file suffix may be adjusted to match the resolved writer.
  • field_config – Optional writer configuration.
• Returns: Path to the written artifact.