DashScope Python SDK¶
dashscope SDK 是
阿里云百炼(Model Studio)
的官方 Python 客户端:对话补全、多模态理解、向量嵌入、重排序、
图像与视频生成、语音合成与识别、实时语音、微调、智能体强化学习、
托管智能体与应用调用。
dashscope SDK 是类型化、资源式客户端——dashscope.Client()——沿用 OpenAI SDK
的使用体验:一个客户端持有共享连接池,每种能力以类型化资源挂在
其上,响应是类型化对象,失败默认抛出异常。
迁移既有 1.x 代码?见从 1.x 迁移。
特性¶
-
类型化资源
client.chat、client.images、client.audio……每种能力都以 类型化资源挂在同一个客户端上。 -
同步与异步
AsyncClient镜像同步接口,切换到await即可。 -
三种协议
同一个客户端支持
native、openai、anthropic三种传输协议。 -
像读文本一样的流式
像遍历普通文本一样迭代
.text_stream/.reasoning_stream。 -
类型化错误与自诊断
异常携带
code与request_id;可选本地自诊断,另有离线 dev mock。 -
真正的命令行
在 shell 里脚本化所有资源;裸跑
dashscope则打开 SDK Expert AI 助手(AgenticX)。
完整列表见特性。
要求¶
- Python 3.9+(可选交互式助手需要 3.10+)。
- 百炼 API Key——在百炼控制台 创建后导出:
export DASHSCOPE_API_KEY="sk-..."
安装¶
pip install -U dashscope
基础安装覆盖 SDK API 调用、dashscope CLI、Agentic RL 微调与本地
分词器。可选 extras 用于配置交互式 AI 助手,例如
pip install "dashscope[expert]"(见
SDK 专家(AgenticX))。
示例¶
创建它¶
import dashscope
client = dashscope.Client() # 读取 DASHSCOPE_API_KEY
运行它¶
resp = client.chat.completions.create(
model="qwen-plus",
messages=[{"role": "user", "content": "讲个笑话"}],
)
print(resp.output_text)
print(resp.usage.total_tokens)
或一行式:dashscope.chat("qwen-plus", "讲个笑话")。
import asyncio
import dashscope
async def main():
async with dashscope.AsyncClient() as client:
resp = await client.chat.completions.create(
model="qwen-plus",
messages=[{"role": "user", "content": "你好!"}],
)
print(resp.output_text)
asyncio.run(main())
流式运行它¶
传入 stream=True 得到 ChatStream。流是一次性的,两种消费方式
二选一——不能先遍历增量、再调用 get_final_message() 聚合:
stream = client.chat.completions.create(
model="qwen-plus",
messages=[{"role": "user", "content": "写一首关于海的俳句"}],
stream=True,
)
for text in stream.text_stream:
print(text, end="", flush=True)
stream = client.chat.completions.create(
model="qwen-plus",
messages=[{"role": "user", "content": "写一首关于海的俳句"}],
stream=True,
)
final = stream.get_final_message() # 消费整个流并组装为类型化响应
print(final.output_text)
流耗尽时自动关闭连接;中途放弃可调用 stream.close() 提前释放。
和它对话(实时语音)¶
client.audio.live 通过 WebSocket 运行全双工语音会话——完整接入
流程见 Qwen Live 指南。
命令行(CLI)¶
安装 SDK 的同时会安装 dashscope 命令。CLI 覆盖主要 SDK 资源,
多数能力可以直接在 shell 里脚本化:
dashscope version # 打印 SDK 版本
dashscope auth login # 保存 API Key
dashscope chat create --model qwen-plus --prompt "你好!"
dashscope -o json ft list # 机器可读输出,便于脚本处理
覆盖对话、多模态、向量嵌入、图像/视频、音频、文件、微调、智能体
强化学习等能力,并提供协议、区域与输出格式等全局选项。不带任何
参数运行 dashscope 会启动可选的交互式 AI 助手
(pip install "dashscope[expert]")。冻结的 1.x 命令树仍以
dashscope1 提供。详见命令行工具。
AI 助手(SDK Expert)¶
不带参数运行 dashscope(或 dashscope expert)会启动
DashScope SDK Expert——由 AgenticX 驱动的智能体助手,直接在
终端里解答 SDK 问题、生成可运行示例、诊断错误。需要 Python 3.10+
与可选 extra:
pip install -U "dashscope[expert]"
dashscope # 交互式助手
dashscope expert "如何流式输出对话结果?" # 一次性提问后退出
启动方式、首次运行的 Expert 配置与故障排查见 SDK 专家(AgenticX)。
协议¶
同一个调用可以使用三种传输协议:
client = dashscope.Client(protocol="openai") # 或 "native"、"anthropic"
见协议适配器。
错误与诊断¶
失败抛出类型化 DashScopeError 子类,携带 code、request_id 与
响应体;可选的本地诊断在 error.diagnosis 上附加结构化修复建议。
见错误(Errors)与开发工具。
旧版 1.x¶
完整 1.x 接口仍可从历史导入路径使用
(from dashscope import Generation),由冻结门面实现。
见旧版 1.x。
依赖关系¶
基础安装引入 requests、aiohttp、httpx + httpx-sse、
websocket-client、pydantic(v2)、tenacity、tiktoken,以及
CLI 所需的 typer + rich。可选助手 extras 见上文「安装」一节。
许可证¶
本项目采用 Apache License 2.0 授权。