Inference API Documentation#

Pipeline#

Date: 2024-11-25 07:29:21 LastEditors: caishaofei caishaofei@stu.pku.edu.cn LastEditTime: 2024-11-25 12:40:22 FilePath: /MineStudio/minestudio/inference/pipeline.py

class minestudio.inference.pipeline.EpisodePipeline(episode_generator: EpisodeGenerator, episode_filter: EpisodeFilter | List[EpisodeFilter] | None = None, episode_recorder: EpisodeRecorder | None = None)[source]#

A pipeline for generating, filtering, and recording episodes.

Parameters:

  • episode_generator (EpisodeGenerator) – An instance of EpisodeGenerator.

  • episode_filter (Optional[Union[EpisodeFilter, List[EpisodeFilter]]]) – An instance of EpisodeFilter or a list of EpisodeFilter instances. Defaults to None.

  • episode_recorder (Optional[EpisodeRecorder]) – An instance of EpisodeRecorder. Defaults to None.

run()[source]#

Runs the episode pipeline.

The pipeline generates an episode, filters it, and then records it.

Returns:

A summary of the recorded episode.

Return type:

Any

Filter#

Date: 2024-11-25 07:36:18 LastEditors: caishaofei caishaofei@stu.pku.edu.cn LastEditTime: 2024-11-25 12:33:00 FilePath: /MineStudio/minestudio/inference/filter/base_filter.py

class minestudio.inference.filter.base_filter.EpisodeFilter[source]#

Base class for episode filters.

Filters are used to process episodes generated by an EpisodeGenerator.

filter(episode_generator: Generator) → Generator[source]#

Filters an episode generator.

This method should be overridden by subclasses to implement specific filtering logic. By default, it returns the original generator without any filtering.

Parameters:

episode_generator (Generator) – A generator that yields episodes.

Returns:

A generator that yields filtered episodes.

Return type:

Generator

Date: 2024-11-25 12:39:01 LastEditors: caishaofei caishaofei@stu.pku.edu.cn LastEditTime: 2025-01-07 08:19:00 FilePath: /MineStudio/minestudio/inference/filter/info_base_filter.py

class minestudio.inference.filter.info_base_filter.InfoBaseFilter(key: str, regex: str, num: int, label: str = 'status')[source]#

A filter that filters episodes based on information extracted from a specified key in the episode’s info.

It uses a regular expression to match events in the info and counts the occurrences. If the total count meets a specified number, the episode is labeled.

Parameters:

  • key (str) – The key in the episode info to extract data from.

  • regex (str) – The regular expression to match events.

  • num (int) – The minimum number of matched events required for an episode to pass the filter.

  • label (str) – The label to assign to the episode if it passes the filter. Defaults to “status”.

filter(episode_generator)[source]#

Filters episodes based on the specified criteria.

For each episode, it loads the info, extracts data based on the key, matches events using the regex, and counts the occurrences. If the total count is greater than or equal to num, the episode is labeled.

Parameters:

episode_generator (Generator) – A generator that yields episodes.

Returns:

A generator that yields filtered episodes.

Return type:

Generator

Generator#

Date: 2024-11-25 07:36:18 LastEditors: caishaofei caishaofei@stu.pku.edu.cn LastEditTime: 2024-11-25 12:06:21 FilePath: /MineStudio/minestudio/inference/generator/base_generator.py

class minestudio.inference.generator.base_generator.AgentInterface[source]#

Interface for an agent that can interact with an environment.

abstract get_action(input: Dict, state: Any, **kwargs) → Tuple[Any, Any][source]#

Gets an action from the agent.

This method must be implemented by subclasses to define how the agent selects an action based on the input and current state.

Parameters:

  • input (Dict) – The input to the agent (e.g., observations from the environment).

  • state (Any) – The current state of the agent.

  • kwargs – Additional keyword arguments.

Returns:

A tuple containing the action selected by the agent and the updated state.

Return type:

Tuple[Any, Any]

class minestudio.inference.generator.base_generator.EpisodeGenerator[source]#

Base class for episode generators.

Generators are responsible for creating sequences of experiences (episodes).

abstract generate() → Generator[source]#

Generates episodes.

This method must be implemented by subclasses to define how episodes are generated.

Returns:

A generator that yields episodes.

Return type:

Generator

Date: 2024-11-25 08:35:59 LastEditors: caishaofei caishaofei@stu.pku.edu.cn LastEditTime: 2024-12-02 11:59:51 FilePath: /MineStudio/minestudio/inference/generator/mine_generator.py

class minestudio.inference.generator.mine_generator.MineGenerator(num_workers: int = 1, num_gpus: float = 0.5, max_restarts: int = 3, **worker_kwargs)[source]#

A generator for Minecraft episodes using multiple parallel workers.

This class manages multiple Worker instances (potentially distributed with Ray) to generate Minecraft episodes in parallel.

Parameters:

  • num_workers (int) – The number of parallel workers to use. Defaults to 1.

  • num_gpus (float) – The number of GPUs to assign to each Ray worker. Defaults to 0.5.

  • max_restarts (int) – The maximum number of times a Ray worker can be restarted if it fails. Defaults to 3.

  • worker_kwargs – Keyword arguments to pass to the Worker constructor.

generate() → Generator[Dict, None, None][source]#

Generates episodes in parallel using the workers.

Uses ray.wait to get completed episodes from the workers. When a worker finishes an episode, it yields the episode data and assigns the worker to generate another episode.

Returns:

A generator that yields dictionaries of file paths for each episode.

Return type:

Generator[Dict, None, None]

class minestudio.inference.generator.mine_generator.Worker(env_generator: Callable, agent_generator: Callable, num_max_steps: int, num_episodes: int, tmpdir: str | None = None, image_media: Literal['h264', 'jpeg'] = 'h264', **unused_kwargs)[source]#

A worker class for generating episodes.

This class handles the interaction between an environment and an agent to generate a specified number of episodes, each with a maximum number of steps. It saves the generated data (images, actions, infos) to files.

Parameters:

  • env_generator (Callable) – A function that generates an environment instance.

  • agent_generator (Callable) – A function that generates an agent instance.

  • num_max_steps (int) – The maximum number of steps per episode.

  • num_episodes (int) – The number of episodes to generate.

  • tmpdir (Optional[str]) – The temporary directory to save episode data. Defaults to None.

  • image_media (Literal["h264", "jpeg"]) – The format to save images (“h264” or “jpeg”). Defaults to “h264”.

  • unused_kwargs – Additional unused keyword arguments.

append_image_and_info(info: Dict, images: List, infos: List)[source]#

Appends image and info data to the respective lists.

The ‘pov’ (point of view) image is extracted from the info dictionary. The info dictionary is cleaned to ensure all values are of basic dict type if they have a ‘values’ attribute.

Parameters:

  • info (Dict) – The info dictionary from the environment.

  • images (List) – The list to append the image to.

  • infos (List) – The list to append the cleaned info to.

get_next()[source]#

Gets the next generated episode.

Returns:

The next episode data (dictionary of file paths), or None if generation is complete.

Return type:

Optional[Dict]

Raises:

ValueError – If the generator is not initialized.

save_to_file(images: List, actions: List, infos: List)[source]#

Saves the episode data (images, actions, infos) to files.

Generates a unique episode ID and saves infos and actions as pickle files. Saves images as an H264 video or a series of JPEG images based on self.image_media.

Parameters:

  • images (List) – A list of images (frames) from the episode.

  • actions (List) – A list of actions taken during the episode.

  • infos (List) – A list of info dictionaries from the episode.

Returns:

A dictionary containing the paths to the saved files.

Return type:

Dict

Raises:

ValueError – If self.image_media is not “h264” or “jpeg”.

Recorder#

Date: 2024-11-25 07:35:51 LastEditors: caishaofei caishaofei@stu.pku.edu.cn LastEditTime: 2024-11-25 12:55:03 FilePath: /MineStudio/minestudio/inference/recorder/base_recorder.py

class minestudio.inference.recorder.base_recorder.EpisodeRecorder[source]#

Base class for episode recorders.

Recorders are used to process and summarize a collection of episodes.

record(episode_generator: Generator) → Dict | str[source]#

Records and summarizes episodes from an episode generator.

This method iterates through the episodes, counts the total number of episodes and the number of episodes marked with “status” == “yes”. It returns a dictionary containing these counts and the ‘yes_rate’.

Parameters:

episode_generator (Generator) – A generator that yields episodes.

Returns:

A dictionary with a summary of the episodes, including ‘num_yes’, ‘num_episodes’, and ‘yes_rate’.

Return type:

Union[Dict, str]