[Feat] Move config to kwargs and Give Clearer Error Message on Unsupported API Types

Author: juncaipeng

docs/authentication.md

@@ -37,13 +37,13 @@ erniebot.ak = "<EB-ACCESS-KEY>"
 erniebot.sk = "<EB-SECRET-KEY>"
 ```
 
-3) 使用`config`参数：
+3) 使用`_config_`参数：
 ``` {.py .copy}
 import erniebot
 
 # Take erniebot.ChatCompletion as an example
 chat_completion = erniebot.ChatCompletion.create(
-    config=dict(
+    _config_=dict(
         api_type="<EB-API-TYPE>",
         ak="<EB-ACCESS-KEY>",
         sk="<EB-SECRET-KEY>",
@@ -58,7 +58,7 @@ chat_completion = erniebot.ChatCompletion.create(
 
 注意事项：
 
-* 允许同时使用多种方式设置鉴权信息，程序将根据设置方式的优先级确定配置项的最终取值。三种设置方式的优先级从高到低依次为：使用`config`参数，使用全局变量，使用环境变量。
+* 允许同时使用多种方式设置鉴权信息，程序将根据设置方式的优先级确定配置项的最终取值。三种设置方式的优先级从高到低依次为：使用`_config_`参数，使用全局变量，使用环境变量。
 * **使用特定模型，请准确设置对应后端平台的认证鉴权参数。**
 
 ## 申请千帆大模型平台的AK/SK

erniebot/resources/abc/creatable.py

@@ -26,37 +26,28 @@ class Creatable(Resource, Protocol):
     """Creatable resource protocol."""
 
     @classmethod
-    def create(cls,
-               *,
-               config: Optional[Dict[str, Any]]=None,
-               **create_kwargs: Any) -> Union[EBResponse, Iterator[EBResponse]]:
-        """Create a new resource.
-
-        Args:
-            config: Configuration dictionary.
-            **create_kwargs: Parameters for creating the resource.
-
-        Returns:
-            Response from the server.
-        """
-        config = config or {}
+    def create(cls, **kwargs: Any) -> Union[EBResponse, Iterator[EBResponse]]:
+        """Create a resource."""
+        config = kwargs.pop('_config_', {})
         resource = cls.new_object(**config)
+        create_kwargs = kwargs
         return resource.create_resource(**create_kwargs)
 
     @classmethod
     async def acreate(
-        cls, *, config: Optional[Dict[str, Any]]=None,
-        **create_kwargs: Any) -> Union[EBResponse, AsyncIterator[EBResponse]]:
+        cls, **kwargs: Any) -> Union[EBResponse, AsyncIterator[EBResponse]]:
         """Asynchronous version of `create`."""
-        config = config or {}
+        config = kwargs.pop('_config_', {})
         resource = cls.new_object(**config)
+        create_kwargs = kwargs
         resp = await resource.acreate_resource(**create_kwargs)
         return resp
 
     def create_resource(
-            self, **kwargs: Any) -> Union[EBResponse, Iterator[EBResponse]]:
+            self,
+            **create_kwargs: Any) -> Union[EBResponse, Iterator[EBResponse]]:
         url, params, headers, files, stream, request_timeout = self._prepare_create(
-            kwargs)
+            create_kwargs)
         resp = self.request(
             method='POST',
             url=url,
@@ -70,9 +61,10 @@ def create_resource(
         return resp
 
     async def acreate_resource(
-        self, **kwargs: Any) -> Union[EBResponse, AsyncIterator[EBResponse]]:
+        self,
+        **create_kwargs: Any) -> Union[EBResponse, AsyncIterator[EBResponse]]:
         url, params, headers, files, stream, request_timeout = self._prepare_create(
-            kwargs)
+            create_kwargs)
         resp = await self.arequest(
             method='POST',
             url=url,

erniebot/resources/abc/protocol.py

@@ -29,7 +29,7 @@ class Resource(Protocol):
     """
 
     @classmethod
-    def new_object(cls, **kwargs: Any) -> Self:
+    def new_object(cls, **config: Any) -> Self:
         ...
 
     def request(

erniebot/resources/chat_completion.py

@@ -24,6 +24,8 @@
 class ChatCompletion(EBResource, Creatable):
     """Given a conversation, get a new reply from the model."""
 
+    SUPPORTED_API_TYPES: ClassVar[Tuple[APIType, ...]] = (APIType.QIANFAN,
+                                                          APIType.AI_STUDIO)
     _API_INFO_DICT: ClassVar[Dict[APIType, Dict[str, Any]]] = {
         APIType.QIANFAN: {
             'prefix': 'chat',
@@ -85,14 +87,15 @@ def _set_val_if_key_exists(src: dict, dst: dict, key: str) -> None:
         messages = kwargs['messages']
 
         # url
-        if self.api_type in self._API_INFO_DICT:
+        if self.api_type in self.SUPPORTED_API_TYPES:
             api_info = self._API_INFO_DICT[self.api_type]
             if model not in api_info['models']:
                 raise errors.InvalidArgumentError(
                     f"{repr(model)} is not a supported model.")
             url = f"/{api_info['prefix']}/{api_info['models'][model]['suffix']}"
         else:
-            raise errors.UnsupportedAPITypeError
+            raise errors.UnsupportedAPITypeError(
+                f"Supported API types: {self.get_supported_api_type_names()}")
 
         # params
         params = {}

erniebot/resources/chat_file.py

@@ -24,6 +24,8 @@
 class ChatFile(EBResource, Creatable):
     """Chat with the model about the content of a given file."""
 
+    SUPPORTED_API_TYPES: ClassVar[Tuple[APIType, ...]] = (APIType.QIANFAN, )
+
     def _prepare_create(self,
                         kwargs: Dict[str, Any]) -> Tuple[str,
                                                          Optional[ParamsType],
@@ -46,10 +48,12 @@ def _prepare_create(self,
         messages = kwargs['messages']
 
         # url
+        assert self.SUPPORTED_API_TYPES == (APIType.QIANFAN, )
         if self.api_type is APIType.QIANFAN:
             url = "/chat/chatfile_adv"
         else:
-            raise errors.UnsupportedAPITypeError
+            raise errors.UnsupportedAPITypeError(
+                f"Supported API types: {self.get_supported_api_type_names()}")
 
         # params
         params = {}

erniebot/resources/embedding.py

@@ -24,6 +24,8 @@
 class Embedding(EBResource, Creatable):
     """Get the embeddings of a given text input."""
 
+    SUPPORTED_API_TYPES: ClassVar[Tuple[APIType, ...]] = (APIType.QIANFAN,
+                                                          APIType.AI_STUDIO)
     _API_INFO_DICT: ClassVar[Dict[APIType, Dict[str, Any]]] = {
         APIType.QIANFAN: {
             'prefix': 'embeddings',
@@ -74,14 +76,15 @@ def _set_val_if_key_exists(src: dict, dst: dict, key: str) -> None:
         input = kwargs['input']
 
         # url
-        if self.api_type in self._API_INFO_DICT:
+        if self.api_type in self.SUPPORTED_API_TYPES:
             api_info = self._API_INFO_DICT[self.api_type]
             if model not in api_info['models']:
                 raise errors.InvalidArgumentError(
                     f"{repr(model)} is not a supported model.")
             url = f"/{api_info['prefix']}/{api_info['models'][model]['suffix']}"
         else:
-            raise errors.UnsupportedAPITypeError
+            raise errors.UnsupportedAPITypeError(
+                f"Supported API types: {self.get_supported_api_type_names()}")
 
         # params
         params = {}

erniebot/resources/image.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import (Any, Dict, Optional, Tuple)
+from typing import (Any, ClassVar, Dict, Optional, Tuple)
 
 from typing_extensions import TypeAlias
 
@@ -25,18 +25,25 @@
 
 class _Image(EBResource):
     @classmethod
-    def create(cls, **create_kwargs: Any) -> EBResponse:
-        resource = cls.new_object()
+    def create(cls, **kwargs: Any) -> EBResponse:
+        """Create a resource."""
+        config = kwargs.pop('_config_', {})
+        resource = cls.new_object(**config)
+        create_kwargs = kwargs
         return resource.create_resource(**create_kwargs)
 
     @classmethod
-    async def acreate(cls, **create_kwargs: Any) -> EBResponse:
-        resource = cls.new_object()
+    async def acreate(cls, **kwargs: Any) -> EBResponse:
+        """Asynchronous version of `create`."""
+        config = kwargs.pop('_config_', {})
+        resource = cls.new_object(**config)
+        create_kwargs = kwargs
         resp = await resource.acreate_resource(**create_kwargs)
         return resp
 
-    def create_resource(self, **kwargs: Any) -> EBResponse:
-        url, params, headers, request_timeout = self._prepare_paint(kwargs)
+    def create_resource(self, **create_kwargs: Any) -> EBResponse:
+        url, params, headers, request_timeout = self._prepare_paint(
+            create_kwargs)
         resp_p = self.request(
             method='POST',
             url=url,
@@ -59,8 +66,9 @@ def create_resource(self, **kwargs: Any) -> EBResponse:
 
         return resp_f
 
-    async def acreate_resource(self, **kwargs: Any) -> EBResponse:
-        url, params, headers, request_timeout = self._prepare_paint(kwargs)
+    async def acreate_resource(self, **create_kwargs: Any) -> EBResponse:
+        url, params, headers, request_timeout = self._prepare_paint(
+            create_kwargs)
         resp_p = await self.arequest(
             method='POST',
             url=url,
@@ -105,6 +113,8 @@ def _check_status(resp: EBResponse) -> bool:
 class ImageV1(_Image):
     """Generate a new image based on a given prompt."""
 
+    SUPPORTED_API_TYPES: ClassVar[Tuple[APIType, ...]] = (APIType.YINIAN, )
+
     def _prepare_paint(self,
                        kwargs: Dict[str, Any]) -> Tuple[str,
                                                         Optional[ParamsType],
@@ -141,10 +151,12 @@ def _set_val_if_key_exists(src: dict, dst: dict, key: str) -> None:
         style = kwargs['style']
 
         # url
+        assert self.SUPPORTED_API_TYPES == (APIType.YINIAN, )
         if self.api_type is APIType.YINIAN:
             url = "/txt2img"
         else:
-            raise errors.UnsupportedAPITypeError
+            raise errors.UnsupportedAPITypeError(
+                f"Supported API types: {self.get_supported_api_type_names()}")
 
         # params
         params = {}
@@ -166,10 +178,12 @@ def _prepare_fetch(self, resp_p: EBResponse) -> Tuple[str,
                                                           Optional[HeadersType],
                                                           ]:
         # url
+        assert self.SUPPORTED_API_TYPES == (APIType.YINIAN, )
         if self.api_type is APIType.YINIAN:
             url = "/getImg"
         else:
-            raise errors.UnsupportedAPITypeError
+            raise errors.UnsupportedAPITypeError(
+                f"Supported API types: {self.get_supported_api_type_names()}")
 
         # params
         params = {}
@@ -189,6 +203,8 @@ def _check_status(resp: EBResponse) -> bool:
 class ImageV2(_Image):
     """Generate a new image based on a given prompt."""
 
+    SUPPORTED_API_TYPES: ClassVar[Tuple[APIType, ...]] = (APIType.YINIAN, )
+
     def _prepare_paint(self,
                        kwargs: Dict[str, Any]) -> Tuple[str,
                                                         Optional[ParamsType],
@@ -231,13 +247,15 @@ def _set_val_if_key_exists(src: dict, dst: dict, key: str) -> None:
         height = kwargs['height']
 
         # url
+        assert self.SUPPORTED_API_TYPES == (APIType.YINIAN, )
         if self.api_type is APIType.YINIAN:
             url = "/txt2imgv2"
             if model != 'ernie-vilg-v2':
                 raise errors.InvalidArgumentError(
                     f"{repr(model)} is not a supported model.")
         else:
-            raise errors.UnsupportedAPITypeError
+            raise errors.UnsupportedAPITypeError(
+                f"Supported API types: {self.get_supported_api_type_names()}")
 
         # params
         params = {}
@@ -260,10 +278,12 @@ def _prepare_fetch(self, resp_p: EBResponse) -> Tuple[str,
                                                           Optional[HeadersType],
                                                           ]:
         # url
+        assert self.SUPPORTED_API_TYPES == (APIType.YINIAN, )
         if self.api_type is APIType.YINIAN:
             url = "/getImgv2"
         else:
-            raise errors.UnsupportedAPITypeError
+            raise errors.UnsupportedAPITypeError(
+                f"Supported API types: {self.get_supported_api_type_names()}")
 
         # params
         params = {}

erniebot/resources/resource.py

@@ -13,13 +13,15 @@
 # limitations under the License.
 
 import asyncio
+import operator
 import time
-from typing import (Any, AsyncIterator, Callable, cast, Dict, Iterator,
-                    Optional, Union)
+from typing import (Any, AsyncIterator, Callable, cast, ClassVar, Dict,
+                    Iterator, List, Optional, Tuple, Union)
 
 from typing_extensions import final, Self
 
 import erniebot.errors as errors
+from erniebot.api_types import APIType
 from erniebot.backends import build_backend, convert_str_to_api_type
 from erniebot.client import EBClient
 from erniebot.config import GlobalConfig
@@ -41,20 +43,18 @@ class EBResource(object):
     facilitate reuse of concrete implementations. Most methods of this class are
     marked as final (e.g., `request`, `arequest`), while some methods can be
     overridden to change the default behavior (e.g., `_create_config_dict`).
-
-    Attributes:
-        cfg (Dict[str, Any]): Dictionary that stores global settings.
-        client (erniebot.client.EBClient): Low-level client instance.
     """
 
+    SUPPORTED_API_TYPES: ClassVar[Tuple[APIType, ...]] = ()
+
     MAX_POLLING_RETRIES: int = 20
     POLLING_INTERVAL: int = 5
     _MAX_TOKEN_UPDATE_RETRIES: int = 3
 
-    def __init__(self, **kwargs: Any) -> None:
+    def __init__(self, **config: Any) -> None:
         super().__init__()
 
-        self._cfg = self._create_config_dict(**kwargs)
+        self._cfg = self._create_config_dict(config)
 
         self.api_type = self._cfg['api_type']
         self.timeout = self._cfg['timeout']
@@ -67,6 +67,10 @@ def __init__(self, **kwargs: Any) -> None:
     def new_object(cls, **kwargs: Any) -> Self:
         return cls(**kwargs)
 
+    @classmethod
+    def get_supported_api_type_names(cls) -> List[str]:
+        return list(map(operator.attrgetter('name'), cls.SUPPORTED_API_TYPES))
+
     @final
     def request(
             self,
@@ -285,7 +289,7 @@ async def _arequest(
                 else:
                     raise
 
-    def _create_config_dict(self, **overrides: Any) -> Dict[str, Any]:
+    def _create_config_dict(self, overrides: Any) -> Dict[str, Any]:
         cfg_dict = cast(Dict[str, Any], GlobalConfig().create_dict(**overrides))
         api_type_str = cfg_dict['api_type']
         if not isinstance(api_type_str, str):

examples/requirements.txt

@@ -1 +1,2 @@
 gradio
+numpy

requirements.txt

@@ -1,6 +1,5 @@
 aiohttp
 bce-python-sdk
 colorlog
-numpy
 requests >= 2.20
 typing_extensions

tests/embedding.py

@@ -1,4 +1,3 @@
-import numpy as np
 import erniebot
 
 if __name__ == '__main__':