Skip to content

Commit d692998

Browse files
docs(region): note region-specific API keys and region quirks
API keys cannot be mixed across regions (401 on mismatch), so document this next to set_region in both READMEs and the sample. Also document US -us model suffix, EU/JP workspace deployment scope, feature availability limits, and shared-domain overrides. Derive the set_region region list from env.MAAS_REGIONS to prevent drift.
1 parent a1cdf73 commit d692998

4 files changed

Lines changed: 30 additions & 11 deletions

File tree

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,14 @@ Supported regions:
119119
| `eu-central-1` | Germany (Frankfurt) |
120120
| `us-east-1` | US (Virginia) |
121121

122+
> **API keys are region-specific.** Each region issues its own API keys (`sk-` prefix) in its Model Studio console, and keys cannot be mixed across regions — using a key from another region fails with `401`. Switch `api_key` together with the region.
123+
124+
Region-specific notes:
125+
126+
- `eu-central-1` / `ap-northeast-1`: the deployment scope (Global, or EU / Japan) is chosen when the workspace is created in the console, not per API call.
127+
- `us-east-1`: model names with the `-us` suffix (e.g. `qwen-plus-us`) restrict inference to the US; names without the suffix default to global inference.
128+
- Batch inference, model fine-tuning and application development are currently only available in `cn-beijing` and `ap-southeast-1`.
129+
122130
> `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.
123131
124132
### Using environment variables
@@ -138,6 +146,8 @@ When a MaaS region is set via `DASHSCOPE_API_REGION`, the SDK builds the regiona
138146
| `DASHSCOPE_WEBSOCKET_BASE_URL` | WebSocket endpoint (`dashscope.base_websocket_api_url`) |
139147
| `DASHSCOPE_COMPATIBLE_BASE_URL` | OpenAI-compatible endpoint (`dashscope.base_compatible_api_url`) |
140148

149+
`set_region` always builds workspace-exclusive endpoints. Some regions also offer shared domains without a workspace subdomain — `dashscope.aliyuncs.com` (Beijing), `dashscope-intl.aliyuncs.com` (Singapore) and `dashscope-us.aliyuncs.com` (US Virginia); use the override variables above to point at them.
150+
141151
### OpenAI-compatible chat completions
142152

143153
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.

‎README_zh.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,14 @@ print(dashscope.base_http_api_url)
118118
| `eu-central-1` | 德国(法兰克福) |
119119
| `us-east-1` | 美国(弗吉尼亚) |
120120

121+
> **各地域 API Key 相互独立。**每个地域的 API Key(`sk-` 前缀)需在对应地域的百炼控制台创建,不可跨地域混用——使用其他地域的 Key 会返回 `401`。切换地域时请同步更换 `api_key`。
122+
123+
地域特殊说明:
124+
125+
- `eu-central-1` / `ap-northeast-1`:部署范围(全球,或欧盟 / 日本)在控制台创建业务空间时选择,不在 API 调用层配置。
126+
- `us-east-1`:模型名带 `-us` 后缀(如 `qwen-plus-us`)限定美国境内推理;不带后缀默认全球推理。
127+
- 批量推理、模型调优、应用开发等高级功能目前仅 `cn-beijing` 与 `ap-southeast-1` 支持。
128+
121129
> `set_region` 修改的是进程级全局变量,因此在单进程同时访问多个区域时并非并发安全。建议在启动时调用一次,或在每次切换前重新调用。
122130
123131
### 使用环境变量
@@ -137,6 +145,8 @@ export DASHSCOPE_WORKSPACE_ID='ws-xxx123' # 用于解析端点子域名
137145
| `DASHSCOPE_WEBSOCKET_BASE_URL` | WebSocket 端点(`dashscope.base_websocket_api_url`) |
138146
| `DASHSCOPE_COMPATIBLE_BASE_URL` | OpenAI-compatible 端点(`dashscope.base_compatible_api_url`) |
139147

148+
`set_region` 构造的始终是业务空间专属域名。部分地域还提供不含 workspace 子域名的共享域名——北京 `dashscope.aliyuncs.com`、新加坡 `dashscope-intl.aliyuncs.com`、美国 `dashscope-us.aliyuncs.com`,如需使用可通过上面的环境变量直接覆盖。
149+
140150
### OpenAI-compatible 对话补全
141151

142152
SDK 提供了 OpenAI-compatible 的对话补全入口,它会请求 `dashscope.base_compatible_api_url`(请求路径 `chat/completions`)——无需额外安装 `openai` 库,并自动跟随上面配置的区域。

‎dashscope/__init__.py‎

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
from dashscope.api_entities.http_request import close_shared_sync_session
3535
from dashscope.common.api_key import save_api_key
3636
from dashscope.common.env import (
37+
MAAS_REGIONS,
3738
api_key,
3839
api_key_file_path,
3940
base_compatible_api_url,
@@ -82,15 +83,9 @@
8283
)
8384

8485

85-
# Supported MaaS regions and their default base URLs
86-
_MAAS_REGIONS = {
87-
"cn-beijing",
88-
"ap-southeast-1",
89-
"us-east-1",
90-
"cn-hongkong",
91-
"eu-central-1",
92-
"ap-northeast-1",
93-
}
86+
# cn-beijing defaults to the legacy dashscope.aliyuncs.com endpoints;
87+
# its MaaS URLs are only reachable via an explicit set_region() call.
88+
_MAAS_REGIONS = {*MAAS_REGIONS, "cn-beijing"}
9489

9590

9691
def set_region(region: str, workspace_id: str = None):

‎samples/set_region_example.py‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44
55
This example shows how to configure the SDK to use different regional
66
endpoints for MaaS (Model as a Service).
7+
8+
Note: API keys are region-specific. Each region requires its own key
9+
created in that region's Model Studio console; using a key from another
10+
region fails with 401.
711
"""
812

913
import dashscope
@@ -31,7 +35,7 @@ def example_generation_call():
3135
response = Generation.call(
3236
model="qwen-max",
3337
messages=[{"role": "user", "content": "Hello, world!"}],
34-
api_key="your-api-key", # Replace with your actual API key
38+
api_key="your-api-key", # must be created in this region
3539
)
3640
print(response)
3741

@@ -46,7 +50,7 @@ def example_chat_completion():
4650
response = Completions.create(
4751
model="qwen-max",
4852
messages=[{"role": "user", "content": "你好,世界!"}],
49-
api_key="your-api-key", # Replace with your actual API key
53+
api_key="your-api-key", # must be created in this region
5054
stream=False,
5155
)
5256
print(response)

0 commit comments

Comments
 (0)