Skip to content

Commit ed09076

Browse files
feat(acli): tongyi native DashScope route + expert guide surfaces
- providers/tongyi: switch from compatible-mode to the native generation route so calls land in the native SLS logstore; per-model text/multimodal-generation endpoint fallback covering both the HTTP-400 and the 200-SSE error-event variants of "url error"; content parts/tool calls converted to the native shape - embedded/sdk: new module + guide_url params; the dashscope expert entry stamps x-dashscope-sdk-client as acli/<version>/expert and the TUI/REPL startup banners show the locale-aware expert guide link - first-run surfaces: get-api-key and dashscope-sdk-expert links in the no-key gate, the example-download offer, and the example README - README/README_zh: how to obtain an API key + expert guide link - includes the pending acli sync baseline (provider/key wizard fixes, subagents/config/dev/session/adapter updates)
1 parent d265baa commit ed09076

41 files changed

Lines changed: 1552 additions & 1293 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 2 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ else:
5252

5353
## API Key Authentication
5454

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

5757
### Using the API Key
5858

@@ -89,93 +89,13 @@ save_api_key(api_key='YOUR-DASHSCOPE-API-KEY',
8989

9090
```
9191

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-
17392
## AI Assistant: DashScope SDK Expert
17493

17594
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.
17695

17796
- 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
17897
- 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
98+
- Full walkthrough: [DashScope SDK Expert guide](https://help.aliyun.com/en/model-studio/dashscope-sdk-expert)
17999

180100
## Supported Models
181101

‎README_zh.md‎

Lines changed: 2 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ else:
5151

5252
## API Key 鉴权
5353

54-
SDK 使用 API Key 进行鉴权。获取 API Key 的方法请参考[阿里云百炼官方文档(国内站)](https://help.aliyun.com/zh/model-studio/)和[阿里云百炼官方文档(国际站)](https://www.alibabacloud.com/help/en/model-studio/)。
54+
SDK 使用 API Key 进行鉴权。获取 API Key 请参见[如何获取 API Key](https://help.aliyun.com/zh/model-studio/get-api-key),或参考[阿里云百炼官方文档(国内站)](https://help.aliyun.com/zh/model-studio/)和[阿里云百炼官方文档(国际站)](https://www.alibabacloud.com/help/en/model-studio/)。
5555

5656
### 使用 API Key
5757

@@ -88,93 +88,13 @@ save_api_key(api_key='YOUR-DASHSCOPE-API-KEY',
8888

8989
```
9090

91-
## 区域与端点配置
92-
93-
默认情况下,SDK 将请求发往华北2(北京)公共端点 `dashscope.aliyuncs.com`。如果你的百炼(Model Studio)业务空间位于其他区域,请在调用前先切换端点。
94-
95-
### 使用 `set_region`
96-
97-
`dashscope.set_region(region, workspace_id)` 会一次性把 HTTP、WebSocket 和 OpenAI-compatible 三个 base URL 指向指定区域。`workspace_id` 为必填项,会作为端点的子域名。
98-
99-
```python
100-
import dashscope
101-
102-
# 切换到新加坡区域,业务空间为 "ws-xxx123"
103-
dashscope.set_region(region="ap-southeast-1", workspace_id="ws-xxx123")
104-
105-
# 之后所有调用都会使用:
106-
# https://ws-xxx123.ap-southeast-1.maas.aliyuncs.com/api/v1
107-
print(dashscope.base_http_api_url)
108-
```
109-
110-
支持的区域:
111-
112-
| 区域 | 地理位置 |
113-
|--------|----------|
114-
| `cn-beijing` | 华北2(北京) |
115-
| `cn-hongkong` | 中国(香港) |
116-
| `ap-southeast-1` | 新加坡 |
117-
| `ap-northeast-1` | 日本(东京) |
118-
| `eu-central-1` | 德国(法兰克福) |
119-
| `us-east-1` | 美国(弗吉尼亚) |
120-
121-
> **各地域 API Key 相互独立。**每个地域的 API Key(`sk-` 前缀)需在对应地域的百炼控制台创建,不可跨地域混用——使用其他地域的 Key 会返回 `401`。切换地域时请同步更换 `api_key`。
122-
123-
地域特殊说明:
124-
125-
- WebSocket 端点(`wss://.../api-ws/v1/inference`)目前仅 `cn-beijing` 与 `ap-southeast-1` 提供。`set_region` 对所有地域都会设置 `base_websocket_api_url`,但实时语音识别/合成、多模态对话等基于 WebSocket 的实时 API 在其他地域不可用。
126-
- `eu-central-1` / `ap-northeast-1`:部署范围(全球,或欧盟 / 日本)在控制台创建业务空间时选择,不在 API 调用层配置。
127-
- `us-east-1`:模型名带 `-us` 后缀(如 `qwen-plus-us`)限定美国境内推理;不带后缀默认全球推理。
128-
- 批量推理、模型调优、应用开发等高级功能目前仅 `cn-beijing` 与 `ap-southeast-1` 支持。
129-
130-
> `set_region` 修改的是进程级全局变量,因此在单进程同时访问多个区域时并非并发安全。建议在启动时调用一次,或在每次切换前重新调用。
131-
132-
### 使用环境变量
133-
134-
也可以不写代码,直接通过环境变量选择区域:
135-
136-
```shell
137-
export DASHSCOPE_API_REGION='ap-southeast-1' # 默认:cn-beijing
138-
export DASHSCOPE_WORKSPACE_ID='ws-xxx123' # 用于解析端点子域名
139-
```
140-
141-
当通过 `DASHSCOPE_API_REGION` 设置了 MaaS 区域时,SDK 会构造对应的区域端点,并把 `DASHSCOPE_WORKSPACE_ID` 代入其中。你也可以直接覆盖每一个 base URL:
142-
143-
| 环境变量 | 覆盖的对象 |
144-
|----------------------|-----------|
145-
| `DASHSCOPE_HTTP_BASE_URL` | HTTP 端点(`dashscope.base_http_api_url`) |
146-
| `DASHSCOPE_WEBSOCKET_BASE_URL` | WebSocket 端点(`dashscope.base_websocket_api_url`) |
147-
| `DASHSCOPE_COMPATIBLE_BASE_URL` | OpenAI-compatible 端点(`dashscope.base_compatible_api_url`) |
148-
149-
`set_region` 构造的始终是业务空间专属域名。部分地域还提供不含 workspace 子域名的共享域名——北京 `dashscope.aliyuncs.com`、新加坡 `dashscope-intl.aliyuncs.com`、美国 `dashscope-us.aliyuncs.com`,如需使用可通过上面的环境变量直接覆盖。
150-
151-
### OpenAI-compatible 对话补全
152-
153-
SDK 提供了 OpenAI-compatible 的对话补全入口,它会请求 `dashscope.base_compatible_api_url`(请求路径 `chat/completions`)——无需额外安装 `openai` 库,并自动跟随上面配置的区域。
154-
155-
```python
156-
import dashscope
157-
from dashscope.aigc.chat_completion import Completions
158-
159-
dashscope.set_region(region="cn-hongkong", workspace_id="ws-hk-789")
160-
161-
response = Completions.create(
162-
model="qwen-max",
163-
messages=[{"role": "user", "content": "你好"}],
164-
api_key="YOUR-DASHSCOPE-API-KEY",
165-
stream=False, # 设为 True 则返回 ChatCompletionChunk 生成器
166-
)
167-
print(response)
168-
```
169-
170-
完整可运行示例见 [`samples/set_region_example.py`](samples/set_region_example.py)。
171-
17291
## AI 助手:DashScope SDK Expert
17392

17493
SDK 内置了交互式 AI 助手 **DashScope SDK Expert**,基于随包提供的 Agentic CLI(`dashscope/acli`)框架构建。对于 DashScope SDK/CLI 用户,它是获取开发咨询和 AI 编码帮助的推荐方式——直接在终端中解答 SDK/API 问题、生成可运行示例、展示 CLI 用法、诊断错误。
17594

17695
- 直接运行 `dashscope`(不带参数)即可启动助手。首次运行时会提示安装 SDK Expert 知识包(按领域划分的速查技能:文本、多模态、语音、检索、微调、Agent、CLI),使助手的指导来自 SDK 的公开接口——参数、输出、错误码——而无需阅读源码
17796
- 直接提问代替翻文档——如 `dashscope "如何流式输出 Generation 结果"` 或 `dashscope "取消微调任务的 CLI 命令"`。在助手内输入 `/help` 可列出可用命令(`/setup`、`/skill`、`/stats` 等);经典 SDK 子命令依然可用,无法识别的命令会自动转给助手处理
97+
- 完整使用指南:[DashScope SDK Expert 文档](https://help.aliyun.com/zh/model-studio/dashscope-sdk-expert)
17898

17999
## 支持的模型
180100

‎dashscope/__init__.py‎

Lines changed: 0 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,6 @@
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,
3837
api_key,
3938
api_key_file_path,
4039
base_compatible_api_url,
@@ -82,48 +81,6 @@
8281
list_tokenizers,
8382
)
8483

85-
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"}
89-
90-
91-
def set_region(region: str, workspace_id: str = None):
92-
"""Switch to a specific MaaS region.
93-
94-
Updates base_http_api_url, base_compatible_api_url and
95-
base_websocket_api_url to point to the MaaS endpoint for the
96-
given region and workspace.
97-
98-
Args:
99-
region (str): The MaaS region, e.g. "ap-southeast-1",
100-
"us-east-1", "cn-hongkong", "cn-beijing", "eu-central-1",
101-
"ap-northeast-1".
102-
workspace_id (str): The workspace ID, used as the subdomain
103-
of the MaaS endpoint.
104-
105-
Raises:
106-
ValueError: If region is not supported or workspace_id is
107-
empty.
108-
"""
109-
if region not in _MAAS_REGIONS:
110-
raise ValueError(
111-
f"Unsupported region '{region}'. "
112-
f"Supported regions: {sorted(_MAAS_REGIONS)}",
113-
)
114-
115-
if not workspace_id:
116-
raise ValueError("workspace_id is required")
117-
118-
global base_http_api_url, base_compatible_api_url
119-
global base_websocket_api_url
120-
121-
host = f"{workspace_id}.{region}.maas.aliyuncs.com"
122-
base_http_api_url = f"https://{host}/api/v1"
123-
base_compatible_api_url = f"https://{host}/compatible-mode/v1"
124-
base_websocket_api_url = f"wss://{host}/api-ws/v1/inference"
125-
126-
12784
__all__ = [
12885
"__version__",
12986
"base_compatible_api_url",
@@ -184,7 +141,6 @@ def set_region(region: str, workspace_id: str = None):
184141
"MessageFile",
185142
"AssistantFile",
186143
"VideoSynthesis",
187-
"set_region",
188144
]
189145

190146
logging.getLogger(__name__).addHandler(NullHandler())

‎dashscope/__init__.pyi‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@ base_websocket_api_url: str
2323
def save_api_key(api_key: str, file_path: Optional[str] = ...) -> None: ...
2424
def close_shared_aio_session() -> None: ...
2525
def close_shared_sync_session() -> None: ...
26-
def set_region(region: str, workspace_id: Optional[str] = ...) -> None: ...
2726

2827
# ---------------------------------------------------------------------------
2928
# Response types

‎dashscope/acli/agents/subagents.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
Subagents are a subset of capabilities that function as autonomous workers
55
you delegate tasks to (vs. tool capabilities that the main agent calls).
66
Currently: local.subagent (built-in) + extension capabilities that act as
7-
remote agents (e.g., Coze workflows).
7+
remote agents (e.g., a hosted workflow engine).
88
99
The /subagents command provides:
1010
- list: show all discovered subagents with status

‎dashscope/acli/cli/examples.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -256,6 +256,12 @@ def _copy_example_flat(src: Path, dst: Path, *, force: bool) -> bool:
256256
)
257257

258258
console.print(f"[green]✓ Example copied to: {acli_dir}[/green]")
259+
if src.name == "dashscope-sdk-expert":
260+
from dashscope.acli.cli.handlers_key import _GUIDE_DOC, _doc_locale
261+
262+
console.print(
263+
f"[dim]Guide: {_GUIDE_DOC.format(_doc_locale())}[/dim]",
264+
)
259265
if backup_dir is not None:
260266
console.print(
261267
f"[dim]Overwritten files backed up to: {backup_dir} "

‎dashscope/acli/cli/handlers_key.py‎

Lines changed: 38 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,21 @@
1616

1717
console = Console()
1818

19+
# Model Studio doc links for the no-key startup prompt; locale segment
20+
# comes from _doc_locale().
21+
_GET_API_KEY_DOC = "https://help.aliyun.com/{}/model-studio/get-api-key"
22+
_GUIDE_DOC = "https://help.aliyun.com/{}/model-studio/dashscope-sdk-expert"
23+
24+
25+
def _doc_locale() -> str:
26+
"""Pick the help-center locale from the process locale env vars."""
27+
import os
28+
29+
for var in ("LC_ALL", "LC_MESSAGES", "LANG"):
30+
if "zh" in (os.environ.get(var) or "").lower():
31+
return "zh"
32+
return "en"
33+
1934

2035
def all_key_targets(config: Config | None = None) -> dict[str, dict]:
2136
"""Merge KEY_TARGETS (built-in) with extension providers into one dict.
@@ -81,16 +96,35 @@ def ensure_provider_key(config: Config, agent) -> bool:
8196
ext = find_provider(config.provider)
8297
targets = all_key_targets(config)
8398
key_info = targets.get(config.provider)
99+
if ext is None and key_info is None:
100+
# Neither a built-in nor a loaded extension: this directory cannot
101+
# build that provider, so collecting a key is a dead end — and the
102+
# "<PROVIDER>_API_KEY" env var we would suggest is read by nothing.
103+
console.print(
104+
f"\n[yellow]Configured provider '{config.provider}' is not "
105+
"available here (no built-in or loaded extension by that "
106+
"name), so an API key alone will not make it work.[/yellow]"
107+
)
108+
console.print(
109+
"[dim]Starting anyway; run /provider to pick an available "
110+
"provider.[/dim]"
111+
)
112+
return True
113+
84114
if key_info:
85115
env_name = key_info.get("env") or ""
86-
elif ext is not None:
87-
env_name = ext.api_key_env or ""
88116
else:
89-
env_name = f"{config.provider.upper()}_API_KEY"
117+
env_name = ext.api_key_env or ""
90118

91119
console.print(
92120
f"\n[yellow]No API Key detected for " f"{config.provider}[/yellow]",
93121
)
122+
if config.provider.lower() == "tongyi":
123+
lang = _doc_locale()
124+
console.print(
125+
f"[dim]Get an API Key: {_GET_API_KEY_DOC.format(lang)}[/dim]",
126+
)
127+
console.print(f"[dim]Guide: {_GUIDE_DOC.format(lang)}[/dim]")
94128
console.print("Choose how to set it up:")
95129
if env_name:
96130
console.print(f" [1] Set env var {env_name} (exit and set)")
@@ -219,7 +253,7 @@ def _set_extension_provider_token(
219253
console.print("[dim]Cancelled[/dim]")
220254
return False
221255

222-
# Save to the provider's dynamic slot, e.g. ideatalk_api_key.
256+
# Save to the provider's dynamic slot, i.e. <name>_api_key.
223257
old_provider = config.provider
224258
try:
225259
config.provider = ext_prov.name

0 commit comments

Comments
 (0)