feat(region): add multi-region endpoint and workspace support

- Introduce `set_region(region, workspace_id)` to switch HTTP, WebSocket, and OpenAI-compatible endpoints
- Add support for MaaS international regions including Singapore, US East, Hong Kong, Germany, Japan, besides Beijing
- Enable environment variable configuration for region and workspace ID
- Implement runtime resolution of endpoint URLs with `{workspace_id}` placeholder substitution
- Update internal API methods to support per-call workspace parameter for endpoint resolution
- Enhance documentation with detailed usage examples of multi-region configuration
- Add comprehensive unit tests covering region switching, URL resolving, and environment variable handling

Author: luk384090-cloud

README.md

@@ -89,6 +89,76 @@ save_api_key(api_key='YOUR-DASHSCOPE-API-KEY',
 
 ```
 
+## Region and Endpoint Configuration
+
+By default the SDK sends requests to the China (Beijing) public endpoint `dashscope.aliyuncs.com`. If your Model Studio (Bailian) workspace lives in another region, switch the endpoint before making calls.
+
+### Using `set_region`
+
+`dashscope.set_region(region, workspace_id)` points the HTTP, WebSocket and OpenAI-compatible base URLs at the given region in a single call. `workspace_id` is required and is used as the endpoint subdomain.
+
+```python
+import dashscope
+
+# Switch to the Singapore region for workspace "ws-xxx123"
+dashscope.set_region(region="ap-southeast-1", workspace_id="ws-xxx123")
+
+# All subsequent calls use:
+#   https://ws-xxx123.ap-southeast-1.maas.aliyuncs.com/api/v1
+print(dashscope.base_http_api_url)
+```
+
+Supported regions:
+
+| Region | Location |
+|--------|----------|
+| `cn-beijing` | China (Beijing) |
+| `cn-hongkong` | China (Hong Kong) |
+| `ap-southeast-1` | Singapore |
+| `ap-northeast-1` | Japan (Tokyo) |
+| `eu-central-1` | Germany (Frankfurt) |
+| `us-east-1` | US (Virginia) |
+
+> `set_region` updates process-wide globals, so it is not concurrency-safe when a single process talks to multiple regions at the same time. Call it once at startup, or re-call it before each switch.
+
+### Using environment variables
+
+You can also select the region without code:
+
+```shell
+export DASHSCOPE_API_REGION='ap-southeast-1'   # default: cn-beijing
+export DASHSCOPE_WORKSPACE_ID='ws-xxx123'      # used to resolve the endpoint subdomain
+```
+
+When a MaaS region is set via `DASHSCOPE_API_REGION`, the SDK builds the regional endpoints and substitutes `DASHSCOPE_WORKSPACE_ID` into them. You can also override each base URL directly:
+
+| Environment variable | Overrides |
+|----------------------|-----------|
+| `DASHSCOPE_HTTP_BASE_URL` | HTTP endpoint (`dashscope.base_http_api_url`) |
+| `DASHSCOPE_WEBSOCKET_BASE_URL` | WebSocket endpoint (`dashscope.base_websocket_api_url`) |
+| `DASHSCOPE_COMPATIBLE_BASE_URL` | OpenAI-compatible endpoint (`dashscope.base_compatible_api_url`) |
+
+### OpenAI-compatible chat completions
+
+The SDK exposes an OpenAI-compatible chat completions entry that talks to `dashscope.base_compatible_api_url` (request path `chat/completions`) — no extra `openai` package required. It follows the region configured above.
+
+```python
+import dashscope
+from dashscope.aigc.chat_completion import Completions
+
+dashscope.set_region(region="cn-hongkong", workspace_id="ws-hk-789")
+
+response = Completions.create(
+    model="qwen-max",
+    messages=[{"role": "user", "content": "Hello"}],
+    api_key="YOUR-DASHSCOPE-API-KEY",
+    stream=False,  # set True to get a generator of ChatCompletionChunk
+)
+print(response)
+```
+
+A complete runnable example is available in [`samples/set_region_example.py`](samples/set_region_example.py).
+
 ## AI Assistant: DashScope SDK Expert
 
 The SDK ships with an interactive AI assistant, **DashScope SDK Expert**, built on the bundled Agentic CLI (`dashscope/acli`) framework. For DashScope SDK/CLI users it is the recommended way to get development consultation and AI coding help — answering SDK/API questions, generating runnable examples, showing CLI usage, and diagnosing errors, right in your terminal.

README_zh.md

@@ -88,6 +88,76 @@ save_api_key(api_key='YOUR-DASHSCOPE-API-KEY',
 
 ```
 
+## 区域与端点配置
+
+默认情况下，SDK 将请求发往华北2（北京）公共端点 `dashscope.aliyuncs.com`。如果你的百炼（Model Studio）业务空间位于其他区域，请在调用前先切换端点。
+
+### 使用 `set_region`
+
+`dashscope.set_region(region, workspace_id)` 会一次性把 HTTP、WebSocket 和 OpenAI-compatible 三个 base URL 指向指定区域。`workspace_id` 为必填项，会作为端点的子域名。
+
+```python
+import dashscope
+
+# 切换到新加坡区域，业务空间为 "ws-xxx123"
+dashscope.set_region(region="ap-southeast-1", workspace_id="ws-xxx123")
+
+# 之后所有调用都会使用：
+#   https://ws-xxx123.ap-southeast-1.maas.aliyuncs.com/api/v1
+print(dashscope.base_http_api_url)
+```
+
+支持的区域：
+
+| 区域 | 地理位置 |
+|--------|----------|
+| `cn-beijing` | 华北2（北京） |
+| `cn-hongkong` | 中国（香港） |
+| `ap-southeast-1` | 新加坡 |
+| `ap-northeast-1` | 日本（东京） |
+| `eu-central-1` | 德国（法兰克福） |
+| `us-east-1` | 美国（弗吉尼亚） |
+
+> `set_region` 修改的是进程级全局变量，因此在单进程同时访问多个区域时并非并发安全。建议在启动时调用一次，或在每次切换前重新调用。
+
+### 使用环境变量
+
+也可以不写代码，直接通过环境变量选择区域：
+
+```shell
+export DASHSCOPE_API_REGION='ap-southeast-1'   # 默认：cn-beijing
+export DASHSCOPE_WORKSPACE_ID='ws-xxx123'      # 用于解析端点子域名
+```
+
+当通过 `DASHSCOPE_API_REGION` 设置了 MaaS 区域时，SDK 会构造对应的区域端点，并把 `DASHSCOPE_WORKSPACE_ID` 代入其中。你也可以直接覆盖每一个 base URL：
+
+| 环境变量 | 覆盖的对象 |
+|----------------------|-----------|
+| `DASHSCOPE_HTTP_BASE_URL` | HTTP 端点（`dashscope.base_http_api_url`） |
+| `DASHSCOPE_WEBSOCKET_BASE_URL` | WebSocket 端点（`dashscope.base_websocket_api_url`） |
+| `DASHSCOPE_COMPATIBLE_BASE_URL` | OpenAI-compatible 端点（`dashscope.base_compatible_api_url`） |
+
+### OpenAI-compatible 对话补全
+
+SDK 提供了 OpenAI-compatible 的对话补全入口，它会请求 `dashscope.base_compatible_api_url`（请求路径 `chat/completions`）——无需额外安装 `openai` 库，并自动跟随上面配置的区域。
+
+```python
+import dashscope
+from dashscope.aigc.chat_completion import Completions
+
+dashscope.set_region(region="cn-hongkong", workspace_id="ws-hk-789")
+
+response = Completions.create(
+    model="qwen-max",
+    messages=[{"role": "user", "content": "你好"}],
+    api_key="YOUR-DASHSCOPE-API-KEY",
+    stream=False,  # 设为 True 则返回 ChatCompletionChunk 生成器
+)
+print(response)
+```
+
+完整可运行示例见 [`samples/set_region_example.py`](samples/set_region_example.py)。
+
 ## AI 助手：DashScope SDK Expert
 
 SDK 内置了交互式 AI 助手 **DashScope SDK Expert**，基于随包提供的 Agentic CLI（`dashscope/acli`）框架构建。对于 DashScope SDK/CLI 用户，它是获取开发咨询和 AI 编码帮助的推荐方式——直接在终端中解答 SDK/API 问题、生成可运行示例、展示 CLI 用法、诊断错误。

dashscope/__init__.py

@@ -81,6 +81,54 @@
     list_tokenizers,
 )
 
+
+# Supported MaaS regions and their default base URLs
+_MAAS_REGIONS = {
+    "cn-beijing",
+    "ap-southeast-1",
+    "us-east-1",
+    "cn-hongkong",
+    "eu-central-1",
+    "ap-northeast-1",
+}
+
+
+def set_region(region: str, workspace_id: str = None):
+    """Switch to a specific MaaS region.
+
+    Updates base_http_api_url, base_compatible_api_url and
+    base_websocket_api_url to point to the MaaS endpoint for the
+    given region and workspace.
+
+    Args:
+        region (str): The MaaS region, e.g. "ap-southeast-1",
+            "us-east-1", "cn-hongkong", "cn-beijing", "eu-central-1",
+            "ap-northeast-1".
+        workspace_id (str): The workspace ID, used as the subdomain
+            of the MaaS endpoint.
+
+    Raises:
+        ValueError: If region is not supported or workspace_id is
+            empty.
+    """
+    if region not in _MAAS_REGIONS:
+        raise ValueError(
+            f"Unsupported region '{region}'. "
+            f"Supported regions: {sorted(_MAAS_REGIONS)}",
+        )
+
+    if not workspace_id:
+        raise ValueError("workspace_id is required")
+
+    global base_http_api_url, base_compatible_api_url
+    global base_websocket_api_url
+
+    host = f"{workspace_id}.{region}.maas.aliyuncs.com"
+    base_http_api_url = f"https://{host}/api/v1"
+    base_compatible_api_url = f"https://{host}/compatible-mode/v1"
+    base_websocket_api_url = f"wss://{host}/api-ws/v1/inference"
+
+
 __all__ = [
     "__version__",
     "base_compatible_api_url",
@@ -141,6 +189,7 @@
     "MessageFile",
     "AssistantFile",
     "VideoSynthesis",
+    "set_region",
 ]
 
 logging.getLogger(__name__).addHandler(NullHandler())

dashscope/__init__.pyi

@@ -23,6 +23,7 @@ base_websocket_api_url: str
 def save_api_key(api_key: str, file_path: Optional[str] = ...) -> None: ...
 def close_shared_aio_session() -> None: ...
 def close_shared_sync_session() -> None: ...
+def set_region(region: str, workspace_id: Optional[str] = ...) -> None: ...
 
 # ---------------------------------------------------------------------------
 # Response types

dashscope/api_entities/api_request_factory.py

@@ -19,6 +19,7 @@
 from dashscope.common.error import InputDataRequired, UnsupportedApiProtocol
 from dashscope.common.logging import logger
 from dashscope.common.utils import get_sdk_headers
+from dashscope.common.env import resolve_base_url
 from dashscope.protocol.websocket import WebsocketStreamingMode
 
 
@@ -132,9 +133,17 @@ def _build_api_request(  # pylint: disable=too-many-branches
 
     encryption = None
 
+    # Resolve {workspace_id} placeholder for MaaS international regions
+    workspace = kwargs.pop("workspace", None)
+    if base_address is not None:
+        base_address = resolve_base_url(base_address, workspace)
+
     if api_protocol in [ApiProtocol.HTTP, ApiProtocol.HTTPS]:
         if base_address is None:
-            base_address = dashscope.base_http_api_url
+            base_address = resolve_base_url(
+                dashscope.base_http_api_url,
+                workspace,
+            )
         if not base_address.endswith("/"):
             http_url = base_address + "/"
         else:
@@ -176,7 +185,10 @@ def _build_api_request(  # pylint: disable=too-many-branches
         if base_address is not None:
             websocket_url = base_address
         else:
-            websocket_url = dashscope.base_websocket_api_url
+            websocket_url = resolve_base_url(
+                dashscope.base_websocket_api_url,
+                workspace,
+            )
         request = WebSocketRequest(
             url=websocket_url,
             api_key=api_key,

dashscope/api_entities/encryption.py

@@ -18,6 +18,7 @@
     DEFAULT_REQUEST_TIMEOUT_SECONDS,
 )
 from dashscope.common.logging import logger
+from dashscope.common.env import resolve_base_url
 from dashscope.common.utils import get_sdk_headers
 
 
@@ -88,7 +89,10 @@ def get_base64_iv_str(self):
 
     @staticmethod
     def _get_public_keys():
-        url = dashscope.base_http_api_url + "/public-keys/latest"
+        url = (
+            resolve_base_url(dashscope.base_http_api_url)
+            + "/public-keys/latest"
+        )
         headers = {
             "Authorization": f"Bearer {dashscope.api_key}",
             **get_sdk_headers(module="utils"),

dashscope/audio/http_tts/http_speech_synthesizer.py

@@ -203,12 +203,12 @@ def _http_call(
 
         # Get base URL
         import dashscope
+        from dashscope.common.env import resolve_base_url
         from dashscope.common.utils import get_sdk_headers, join_url
 
-        if url:
-            base_url = url
-        else:
-            base_url = dashscope.base_http_api_url
+        if not url:
+            url = dashscope.base_http_api_url
+        base_url = resolve_base_url(url, workspace)
         url_for_call = join_url(
             base_url,
             "services/audio/tts/SpeechSynthesizer",

dashscope/audio/tts_v2/speech_synthesizer.py

@@ -15,6 +15,7 @@
 
 import dashscope
 from dashscope.common.constants import WEBSOCKET_ERROR_CODE
+from dashscope.common.env import resolve_base_url
 from dashscope.common.error import (
     InputRequired,
     InvalidTask,
@@ -491,7 +492,7 @@ def __update_params(  # pylint: disable=redefined-builtin
             raise InputRequired("format is required!")
         if url is None:
             url = dashscope.base_websocket_api_url
-        self.url = url
+        self.url = resolve_base_url(url, workspace)
         self.apikey = dashscope.api_key
         if self.apikey is None:
             raise InputRequired("apikey is required!")