maxframe 2.0.0b2__cp37-cp37m-win32.whl → 2.3.0rc1__cp37-cp37m-win32.whl

maxframe/learn/contrib/llm/core.py

@@ -20,11 +20,16 @@ import pandas as pd
 from ....core.entity.output_types import OutputType
 from ....core.operator.base import Operator
 from ....core.operator.core import TileableOperatorMixin
-from ....dataframe.core import SERIES_TYPE
 from ....dataframe.operators import DataFrameOperatorMixin
 from ....dataframe.utils import parse_index
+from ....serialization.serializables import Int32Field
 from ....serialization.serializables.core import Serializable
-from ....serialization.serializables.field import AnyField, DictField, StringField
+from ....serialization.serializables.field import (
+    AnyField,
+    BoolField,
+    DictField,
+    StringField,
+)
 
 
 class LLM(Serializable):
@@ -39,6 +44,7 @@ class LLMTaskOperator(Operator, DataFrameOperatorMixin):
     model = AnyField("model", default=None)
     params = DictField("params", default=None)
     running_options: Dict[str, Any] = DictField("running_options", default=None)
+    timeout = Int32Field("timeout", default=None)
 
     def __init__(self, output_types=None, **kw):
         if output_types is None:
@@ -53,11 +59,7 @@ class LLMTaskOperator(Operator, DataFrameOperatorMixin):
         col_name = list(outputs.keys())
         columns = parse_index(pd.Index(col_name), store_data=True)
         out_dtypes = pd.Series(list(outputs.values()), index=col_name)
-        index_value = index or (
-            parse_index(pd.RangeIndex(-1), data)
-            if isinstance(data, SERIES_TYPE)
-            else data.index_value
-        )
+        index_value = index or data.index_value
 
         return self.new_dataframe(
             inputs=[data],
@@ -73,3 +75,12 @@ class LLMTextGenOperator(LLMTaskOperator, TileableOperatorMixin):
 
     def get_output_dtypes(self) -> Dict[str, np.dtype]:
         return {"response": np.dtype("O"), "success": np.dtype("bool")}
+
+
+class LLMTextEmbeddingOp(LLMTaskOperator, TileableOperatorMixin):
+    dimensions = Int32Field("dimensions", default=None)
+    encoding_format = StringField("encoding_format", default=None)
+    simple_output = BoolField("simple_output", default=False)
+
+    def get_output_dtypes(self) -> Dict[str, np.dtype]:
+        return {"response": np.dtype("O"), "success": np.dtype("bool")}

maxframe/learn/contrib/llm/deploy/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

maxframe/learn/contrib/llm/deploy/config.py

@@ -0,0 +1,221 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from copy import deepcopy
+from typing import Any, Dict, List, Optional, Union
+
+from .....protocol import Serializable
+from .....serialization.serializables import StringField
+from .....serialization.serializables.field import (
+    DictField,
+    EnumField,
+    Int32Field,
+    ListField,
+)
+from .....serialization.serializables.field_type import FieldTypes
+from .framework import InferenceFrameworkEnum
+
+
+class ModelDeploymentConfig(Serializable):
+    """
+    Model deployment configuration for extending MaxFrame with custom models.
+
+    This configuration is designed for users who need to deploy models that are not
+    available within MaxFrame's built-in model offerings. It provides a way to specify
+    custom deployment solutions by informing each MaxFrame worker which framework to use,
+    which model path to load, and how to load it.
+
+    The configuration assumes that models are already set up in the container image or
+    mounted paths, and uses the current deploy_config to load them. Users are responsible
+    for ensuring the runtime environment state and compatibility.
+
+    Parameters
+    ----------
+    model_name: str
+        The name of the model.
+    model_file: str
+        The file path of the model.
+    inference_framework_type: InferenceFrameworkEnum
+        The inference framework of the model.
+    required_resource_files: List[Union[str, Any]]
+        The required resource files of the model.
+    load_params: Dict[str, Any]
+        The load params of the model.
+    required_cpu: int
+        The required cpu of the model.
+    required_memory: int
+        The required memory of the model.
+    required_gu: int
+        The required gu of the model.
+    required_gpu_memory: int
+        The required gpu memory of the model.
+    device: str
+        The device of the model. One of "cpu" or "cuda".
+    properties: Dict[str, Any]
+        The properties of the model.
+    tags: List[str]
+        The tags of the model.
+
+    Notes
+    -----
+    - Preview version for model deployments, all fields could be changed in the future.
+
+    **User Responsibility Notice**: Users must have a complete understanding of what
+    they are computing and ensure they fully comprehend the implications of their
+    configuration choices. You are responsible for:
+
+    * Ensuring model compatibility with the specified inference framework
+    * Verifying that model files exist and are accessible in the runtime environment
+    * Confirming that resource requirements (CPU, memory, GPU) are adequate
+    * Validating that all dependencies and libraries are properly installed
+    * Understanding the computational behavior and characteristics of your chosen model
+
+    Examples
+    --------
+    >>> from maxframe.learn.contrib.llm.deploy.config import ModelDeploymentConfig
+    >>> from maxframe.learn.contrib.llm.deploy.framework import InferenceFrameworkEnum
+    >>> from maxframe.learn.contrib.llm.models.managed import ManagedTextGenLLM
+
+    >>> # Configure model deployment with VLLM framework
+    >>> model_config = ModelDeploymentConfig(
+    ...     # Path to the model files (assumed to be available in container/mount)
+    ...     model_file="/models/Qwen3-4B-Instruct-2507-FP8",
+    ...     # Use VLLM serving framework for text generation
+    ...     inference_framework_type=InferenceFrameworkEnum.VLLM_SERVE_TEXT,
+    ...     # Framework-specific loading parameters
+    ...     load_params={
+    ...         "max_context_tokens": 4096,  # Maximum context length for the model
+    ...         "max_startup_wait_seconds": 600  # Max wait time for model startup
+    ...     },
+    ...     # Target device for inference
+    ...     device="cuda",
+    ...     # Resource requirements (2 GPU units)
+    ...     required_gu=2,
+    ...     # Model tags for capabilities
+    ...     tags=["text-generation"],
+    ... )
+
+    >>> # Create managed LLM instance with the deployment configuration
+    >>> llm = ManagedTextGenLLM(name="my-model", deploy_config=model_config)
+    >>> # Generate text using the deployed model.
+    >>> result_df = llm.generate(
+    ...     df,  # Input DataFrame containing prompts
+    ...     prompt_template=messages,  # Template for formatting prompts
+    ...     running_options={
+    ...         "max_context_tokens": 4096,  # Runtime context limit
+    ...     },
+    ...     params={
+    ...         "temperature": 0.7,  # Sampling temperature
+    ...         "max_tokens": 2048  # Maximum tokens to generate
+    ...     },
+    ... )
+
+    To make this model config working with the ManagedTextGenLLM,
+    you need to provide a custom image with the required dependencies and model files.
+
+    """
+
+    model_name: str = StringField("model_name")
+    model_file: str = StringField("model_file")
+    inference_framework_type: InferenceFrameworkEnum = EnumField(
+        "inference_framework_type", enum_type=InferenceFrameworkEnum
+    )
+    required_resource_files: List[Union[str, Any]] = ListField(
+        "required_resource_files", field_type=FieldTypes.any, default_factory=list
+    )
+    load_params: Dict[str, Any] = DictField(
+        "load_params",
+        key_type=FieldTypes.string,
+        value_type=FieldTypes.any,
+        default_factory=dict,
+    )
+    required_cpu: Optional[int] = Int32Field("required_cpu", default=None)
+    required_memory: Optional[int] = Int32Field("required_memory", default=None)
+    required_gu: Optional[int] = Int32Field("required_gu", default=None)
+    required_gpu_memory: Optional[int] = Int32Field("required_gpu_memory", default=None)
+    device: str = StringField("device")
+    properties: Dict[str, Any] = DictField(
+        "properties",
+        key_type=FieldTypes.string,
+        value_type=FieldTypes.any,
+        default_factory=dict,
+    )
+    tags: List[str] = ListField(
+        "tags",
+        field_type=FieldTypes.string,
+        default_factory=list,
+    )
+
+    def is_reasoning_model(self):
+        if self.properties is None:
+            return False
+        return self.properties.get("reasoning_model", False)
+
+    def copy(self) -> "ModelDeploymentConfig":
+        return deepcopy(self)
+
+    def __eq__(self, other):
+        if not isinstance(other, ModelDeploymentConfig):
+            return False
+
+        return (
+            self.model_name == other.model_name
+            and self.model_file == other.model_file
+            and self.inference_framework_type == other.inference_framework_type
+            and self.required_resource_files == other.required_resource_files
+            and self.load_params == other.load_params
+            and self.required_cpu == other.required_cpu
+            and self.required_memory == other.required_memory
+            and self.required_gu == other.required_gu
+            and self.required_gpu_memory == other.required_gpu_memory
+            and self.device == other.device
+            and self.properties == other.properties
+            and self.tags == other.tags
+        )
+
+    def __hash__(self):
+        return hash(
+            (
+                self.model_name,
+                self.model_file,
+                self.inference_framework_type,
+                self.required_resource_files,
+                self.load_params,
+                self.required_cpu,
+                self.required_memory,
+                self.required_gu,
+                self.required_gpu_memory,
+                self.device,
+                self.properties,
+                self.tags,
+            )
+        )
+
+    def check_validity(self):
+        required_fields = [
+            "model_name",
+            "model_file",
+            "inference_framework_type",
+            "device",
+        ]
+        for field in required_fields:
+            if getattr(self, field) is None:
+                raise ValueError(f"{field} is required")
+
+        one_of_fields = ["required_cpu", "required_gu"]
+        if not any(getattr(self, field) is not None for field in one_of_fields):
+            raise ValueError(f"At least one of {one_of_fields} is required")
+
+        if not self.tags:
+            raise ValueError("tags is required")

maxframe/learn/contrib/llm/deploy/core.py

@@ -0,0 +1,247 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any, Dict, List, Optional, Union
+
+from odps.models import Resource as ODPSResource
+
+from .....serialization.serializables import Serializable, StringField
+from .config import ModelDeploymentConfig
+from .framework import InferenceFrameworkEnum
+
+_registered_llm_models = {}
+
+
+class ResourceNameTemplate(Serializable):
+    """
+    A template-based resource name builder that supports variable substitution.
+    All values in the substitution dict will have their hyphens (-) replaced with underscores (_).
+
+    Example:
+        template = ResourceNameTemplate(
+            project="my_project",
+            schema="schema_{region_id}",
+            name="resource_{env}"
+        )
+        # Render with variables
+        full_name = template.build_full_resource_name({"region_id": "cn-hangzhou", "env": "prod"})
+        # Result: resource name with cn_hangzhou and prod substituted
+    """
+
+    project: str = StringField("project", default=None)
+    schema: str = StringField("schema", default=None)
+    name: str = StringField("name")
+
+    def build_full_resource_name(self, template_vars: Dict[str, Any]):
+        """
+        Build full resource name with template variable substitution.
+        """
+        normalized_vars = {
+            key: str(value).replace("-", "_") for key, value in template_vars.items()
+        }
+
+        project, schema, name = self.project, self.schema, self.name
+        res_name = ODPSResource.build_full_resource_name(
+            name=name, project_name=project, schema_name=schema
+        )
+        try:
+            return res_name.format(**normalized_vars)
+        except KeyError:
+            # If template variable is missing, return as-is
+            return res_name
+
+    def __eq__(self, other):
+        if not isinstance(other, ResourceNameTemplate):
+            return False
+        return (
+            self.project == other.project
+            and self.schema == other.schema
+            and self.name == other.name
+        )
+
+    def __hash__(self):
+        return hash((self.project, self.schema, self.name))
+
+    def to_json(self) -> dict:
+        ret = {"name": self.name}
+        if self.project:
+            ret["project"] = self.project
+        if self.schema:
+            ret["schema"] = self.schema
+        return ret
+
+    @classmethod
+    def from_json(cls, serialized: dict) -> "ResourceNameTemplate":
+        kw = serialized.copy()
+        return cls(
+            project=kw.get("project"),
+            schema=kw.get("schema"),
+            name=kw["name"],
+        )
+
+
+def create_model_deployments(
+    model_name: str,
+    model_file: str,
+    inference_frameworks: Union[
+        str, InferenceFrameworkEnum, List[InferenceFrameworkEnum]
+    ],
+    required_resources: List[Union[str, ResourceNameTemplate]] = None,
+    default_load_params: Optional[Dict[str, Any]] = None,
+    required_cpu: Optional[float] = None,
+    required_memory: Optional[int] = None,
+    required_gu: Optional[int] = None,
+    required_gpu_memory: Optional[int] = None,
+    device: str = None,
+    properties: Optional[Dict[str, Any]] = None,
+    tags: Optional[List[str]] = None,
+):
+    frameworks_to_register = (
+        [inference_frameworks]
+        if isinstance(inference_frameworks, (str, InferenceFrameworkEnum))
+        else inference_frameworks
+    )
+
+    deployment_configs = []
+    for inference_framework in frameworks_to_register:
+        inference_framework = (
+            InferenceFrameworkEnum.from_string(inference_framework)
+            if isinstance(inference_framework, str)
+            else inference_framework
+        )
+
+        model_config = ModelDeploymentConfig(
+            model_name=model_name,
+            model_file=model_file,
+            inference_framework_type=inference_framework,
+            required_resource_files=required_resources,
+            load_params=default_load_params,
+            required_cpu=required_cpu,
+            required_memory=required_memory,
+            required_gu=required_gu,
+            required_gpu_memory=required_gpu_memory,
+            device=device,
+            properties=properties,
+            tags=tags,
+        )
+        deployment_configs.append(model_config)
+    return deployment_configs
+
+
+def register_model_deployments(
+    model_name: str,
+    model_file: str,
+    inference_frameworks: Union[
+        str, InferenceFrameworkEnum, List[InferenceFrameworkEnum]
+    ],
+    required_resources: List[Union[str, ResourceNameTemplate]] = None,
+    default_load_params: Optional[Dict[str, Any]] = None,
+    required_cpu: Optional[float] = None,
+    required_memory: Optional[int] = None,
+    required_gu: Optional[int] = None,
+    required_gpu_memory: Optional[int] = None,
+    device: str = None,
+    properties: Optional[Dict[str, Any]] = None,
+    tags: Optional[List[str]] = None,
+):
+    """
+    Register model deployments
+
+    Notes
+    -----
+    - Alpha version for model deployments, all fields could be changed in the future.
+    """
+    model_name = model_name.lower()
+    if not isinstance(inference_frameworks, (InferenceFrameworkEnum, List, str)):
+        raise TypeError(
+            f"inference_framework_type must be type InferenceFrameworkEnum or List[InferenceFrameworkEnum] but {type(inference_frameworks)}"
+        )
+
+    model_deployments = create_model_deployments(
+        model_name=model_name,
+        model_file=model_file,
+        inference_frameworks=inference_frameworks,
+        required_resources=required_resources,
+        default_load_params=default_load_params,
+        required_cpu=required_cpu,
+        required_memory=required_memory,
+        required_gu=required_gu,
+        required_gpu_memory=required_gpu_memory,
+        device=device,
+        properties=properties,
+        tags=tags,
+    )
+
+    for deployment in model_deployments:
+        if model_name not in _registered_llm_models:
+            _registered_llm_models[model_name] = {}
+        if deployment.device not in _registered_llm_models[model_name]:
+            _registered_llm_models[model_name][deployment.device] = {}
+
+        existing = _registered_llm_models[model_name][deployment.device].get(
+            deployment.inference_framework_type
+        )
+
+        if existing:
+            raise ValueError(
+                f"Model {model_name} with {deployment.inference_framework_type} on {deployment.device} already registered"
+            )
+
+        _registered_llm_models[model_name][deployment.device][
+            deployment.inference_framework_type
+        ] = deployment
+
+    return model_deployments
+
+
+def get_registered_model_config(
+    model_name: str,
+    expected_device: Optional[str] = None,
+    expected_inference_framework: Optional[InferenceFrameworkEnum] = None,
+) -> Optional[ModelDeploymentConfig]:
+    model_name = model_name.lower()
+
+    def _load_model_framework_config(framework_configs, expected_framework):
+        if expected_framework is not None:
+            return framework_configs[expected_framework]
+        else:
+            model_config = next(iter(framework_configs.values()))
+            return model_config
+
+    try:
+        if expected_device is not None:
+            model_framework_configs = _registered_llm_models[model_name][
+                expected_device
+            ]
+            return _load_model_framework_config(
+                model_framework_configs, expected_inference_framework
+            )
+        else:
+            model_all_configs = _registered_llm_models[model_name]
+            for device, model_framework_configs in model_all_configs.items():
+                model_config = _load_model_framework_config(
+                    model_framework_configs, expected_inference_framework
+                )
+                if model_config:
+                    return model_config
+    except KeyError:
+        pass
+    except StopIteration:
+        pass
+
+    return None
+
+
+def clean_registered_model():
+    _registered_llm_models.clear()

maxframe/learn/contrib/llm/deploy/framework.py

@@ -0,0 +1,35 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from enum import Enum
+
+
+class InferenceFrameworkEnum(Enum):
+    LLAMA_CPP_PYTHON_TEXT = "LLAMA_CPP_PYTHON:TEXT"
+    LLAMA_CPP_SERVE_TEXT = "LLAMA_CPP_SERVE:TEXT"
+    DASH_SCOPE_TEXT = "DASH_SCOPE:TEXT"
+    DASH_SCOPE_MULTIMODAL = "DASH_SCOPE:MULTIMODAL"
+    VLLM_SERVE_TEXT = "VLLM_SERVE:TEXT"
+    OPENAI_REMOTE_TEXT = "OPENAI_REMOTE:TEXT"
+    OTHER = "OTHER"
+
+    @classmethod
+    def from_string(cls, label):
+        if label is None:
+            return None
+
+        if isinstance(label, cls):
+            return label
+
+        return cls(label)