|
52 | 52 |
|
53 | 53 | ## API Key Authentication |
54 | 54 |
|
55 | | -The SDK uses API key for authentication. To obtain an API Key, see [How to get an API Key](https://help.aliyun.com/en/model-studio/get-api-key). Please refer to [official documentation for alibabacloud china](https://www.alibabacloud.com/help/en/model-studio/) and [official documentation for alibabacloud international](https://www.alibabacloud.com/help/en/model-studio/) regarding how to obtain your api-key. |
| 55 | +The SDK uses API key for authentication. Please refer to [official documentation for alibabacloud china](https://www.alibabacloud.com/help/en/model-studio/) and [official documentation for alibabacloud international](https://www.alibabacloud.com/help/en/model-studio/) regarding how to obtain your api-key. |
56 | 56 |
|
57 | 57 | ### Using the API Key |
58 | 58 |
|
@@ -89,94 +89,12 @@ save_api_key(api_key='YOUR-DASHSCOPE-API-KEY', |
89 | 89 |
|
90 | 90 | ``` |
91 | 91 |
|
92 | | -## Region and Endpoint Configuration |
93 | | - |
94 | | -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. |
95 | | - |
96 | | -### Using `set_region` |
97 | | - |
98 | | -`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. |
99 | | - |
100 | | -```python |
101 | | -import dashscope |
102 | | - |
103 | | -# Switch to the Singapore region for workspace "ws-xxx123" |
104 | | -dashscope.set_region(region="ap-southeast-1", workspace_id="ws-xxx123") |
105 | | - |
106 | | -# All subsequent calls use: |
107 | | -# https://ws-xxx123.ap-southeast-1.maas.aliyuncs.com/api/v1 |
108 | | -print(dashscope.base_http_api_url) |
109 | | -``` |
110 | | - |
111 | | -Supported regions: |
112 | | - |
113 | | -| Region | Location | |
114 | | -|--------|----------| |
115 | | -| `cn-beijing` | China (Beijing) | |
116 | | -| `cn-hongkong` | China (Hong Kong) | |
117 | | -| `ap-southeast-1` | Singapore | |
118 | | -| `ap-northeast-1` | Japan (Tokyo) | |
119 | | -| `eu-central-1` | Germany (Frankfurt) | |
120 | | -| `us-east-1` | US (Virginia) | |
121 | | - |
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 | | -- WebSocket endpoints (`wss://.../api-ws/v1/inference`) are only served in `cn-beijing` and `ap-southeast-1`. `set_region` still sets `base_websocket_api_url` for every region, but WebSocket-based realtime APIs (realtime speech recognition/synthesis, multimodal dialog, etc.) are not available in the other regions. |
127 | | -- `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. |
128 | | -- `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. |
129 | | -- Batch inference, model fine-tuning and application development are currently only available in `cn-beijing` and `ap-southeast-1`. |
130 | | - |
131 | | -> `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. |
132 | | -
|
133 | | -### Using environment variables |
134 | | - |
135 | | -You can also select the region without code: |
136 | | - |
137 | | -```shell |
138 | | -export DASHSCOPE_API_REGION='ap-southeast-1' # default: cn-beijing |
139 | | -export DASHSCOPE_WORKSPACE_ID='ws-xxx123' # used to resolve the endpoint subdomain |
140 | | -``` |
141 | | - |
142 | | -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: |
143 | | - |
144 | | -| Environment variable | Overrides | |
145 | | -|----------------------|-----------| |
146 | | -| `DASHSCOPE_HTTP_BASE_URL` | HTTP endpoint (`dashscope.base_http_api_url`) | |
147 | | -| `DASHSCOPE_WEBSOCKET_BASE_URL` | WebSocket endpoint (`dashscope.base_websocket_api_url`) | |
148 | | -| `DASHSCOPE_COMPATIBLE_BASE_URL` | OpenAI-compatible endpoint (`dashscope.base_compatible_api_url`) | |
149 | | - |
150 | | -`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. |
151 | | - |
152 | | -### OpenAI-compatible chat completions |
153 | | - |
154 | | -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. |
155 | | - |
156 | | -```python |
157 | | -import dashscope |
158 | | -from dashscope.aigc.chat_completion import Completions |
159 | | - |
160 | | -dashscope.set_region(region="cn-hongkong", workspace_id="ws-hk-789") |
161 | | - |
162 | | -response = Completions.create( |
163 | | - model="qwen-max", |
164 | | - messages=[{"role": "user", "content": "Hello"}], |
165 | | - api_key="YOUR-DASHSCOPE-API-KEY", |
166 | | - stream=False, # set True to get a generator of ChatCompletionChunk |
167 | | -) |
168 | | -print(response) |
169 | | -``` |
170 | | - |
171 | | -A complete runnable example is available in [`samples/set_region_example.py`](samples/set_region_example.py). |
172 | | - |
173 | 92 | ## AI Assistant: DashScope SDK Expert |
174 | 93 |
|
175 | 94 | 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. |
176 | 95 |
|
177 | 96 | - Run `dashscope` with no arguments to start the assistant. On first run it offers to install the SDK Expert knowledge pack (per-domain quick-reference skills: text, multimodal, speech, retrieval, fine-tuning, agent, cli), so guidance comes from the SDK's public interfaces — parameters, outputs, error codes — without reading the source |
178 | 97 | - Ask it instead of reading docs — e.g. `dashscope "how do I stream Generation output"` or `dashscope "CLI command to cancel a fine-tuning job"`. Type `/help` inside the assistant to list available commands (`/setup`, `/skill`, `/stats`, ...); classic SDK subcommands still work, and unrecognized commands are routed to the assistant |
179 | | -- Full walkthrough: [DashScope SDK Expert guide](https://help.aliyun.com/en/model-studio/dashscope-sdk-expert) |
180 | 98 |
|
181 | 99 | ## Supported Models |
182 | 100 |
|
|
0 commit comments