阿里云 DashScope 使用指南¶

阿里云 DashScope（通义千问）系列模型。

配置参数¶

核心参数¶

from tfrobot.brain.chain.llms import DashScope

llm = DashScope(
    name="qwen-turbo",
    temperature=0.7,  # 0.0-2.0，控制随机性
    top_p=0.8,  # 0.0-1.0，核采样
    top_k=50,  # 1-∞，top-k 采样
    max_tokens=4096,  # 最大输出 tokens
    stream=False,  # 是否流式输出
)

API 配置¶

from tfrobot.brain.chain.llms import DashScope

llm = DashScope(
    name="qwen-turbo",
    dashscope_api_key="sk-...",  # API 密钥（推荐使用环境变量）
)

互联网搜索¶

DashScope 支持联网搜索功能：

from tfrobot.brain.chain.llms import DashScope
from tfrobot.schema.users import BaseUser

llm = DashScope(
    name="qwen-turbo",
    enable_search=True,  # 启用互联网搜索
)

# 模型会自动搜索最新信息
user = BaseUser(name="用户", uid="1")
# result = llm.complete(current_input=TextMessage(content="今天北京的天气怎么样？", creator=user))

增量输出¶

from tfrobot.brain.chain.llms import DashScope

llm = DashScope(
    name="qwen-turbo",
    incremental_output=True,  # 启用增量输出
)

工具调用¶

原生模式（推荐）¶

from tfrobot.brain.chain.llms import DashScopeWithTools
from tfrobot.brain.chain.prompt.tool_prompt import ToolPrompt
from tfrobot.drive.tool.tool import tool
from tfrobot.schema.message.conversation.message_dto import TextMessage
from tfrobot.schema.users import BaseUser


@tool
def get_weather(city: str) -> str:
    """获取指定城市的天气"""
    return f"{city} 今天晴天，温度 25°C"


llm = DashScopeWithTools(name="qwen-turbo")
llm.system_msg_prompt = [ToolPrompt()]

user = BaseUser(name="用户", uid="1")
result = llm.complete(current_input=TextMessage(content="北京今天的天气怎么样？", creator=user), tools=[get_weather])
print(result.generations[0].tool_calls)
"""
[
    ToolCall(
        index=None,
        call_id='da1970ead3fe4412a9cc1611a291a769',
        tool_type='function',
        function=FunctionCall(name='get_weather', description=None, parameters='{"city": "北京"}'),
    )
]
"""

DashScope vs DashScopeWithTools¶

DashScope：基础模型，需要手动配置 ToolPrompt
DashScopeWithTools：预配置 ToolPrompt，更方便

from tfrobot.brain.chain.llms import DashScope, DashScopeWithTools
from tfrobot.brain.chain.prompt.tool_prompt import ToolPrompt

# 方式一：使用 DashScope
llm = DashScope(name="qwen-turbo")
llm.system_msg_prompt.append(ToolPrompt())

# 方式二：使用 DashScopeWithTools（推荐）
llm = DashScopeWithTools(name="qwen-turbo")

多模态支持¶

图片理解¶

from tfrobot.brain.chain.llms import DashScope
from tfrobot.schema.message.conversation.message_dto import MultiPartMessage
from tfrobot.schema.message.msg_part import ImagePart, ImgUrl, TextPart
from tfrobot.schema.users import BaseUser

llm = DashScope(name="qwen3-vl-flash")
user = BaseUser(name="用户", uid="1")

msg = MultiPartMessage(
    content=[
        TextPart(text="这张图片里有什么？"),
        ImagePart(
            image_url=ImgUrl(
                url="https://bkimg.cdn.bcebos.com/pic/a5c27d1ed21b0ef4bed980d1dfc451da81cb3e0f?x-bce-process=image/format,f_auto",
                mime_type="image/jpeg",
            ),
        ),
    ],
    creator=user,
)

result = llm.complete(current_input=msg)
print(result.generations[0].text)
"""
这张图片展示的是**秦始皇铜车马**，是中国考古史上最重要的发现之一，出土于1980年陕西省西安市临潼区秦始皇陵西侧的铜车马坑。它并非真实使用的交通工具，而是**陪葬品**，用于象征秦始皇的车驾，在他死后随葬于陵墓中，体现其生前的威仪与地位。

具体来看，这个铜车马模型具有以下特征：

1. **四匹铜马**：图中可见四匹并排站立的铜马，每匹都配有精致的笼头、缰绳和装饰，造型逼真，肌肉线条清晰，显示出高超的铸造工艺。
2. **铜御官**：马车前方立有一位铜制御官（车夫）雕像，身着古代服饰，端坐车辕上，手握缰绳，仿佛正在驾驭车马。他的姿态庄重，神态专注。
3. **铜制车舆**：车体结构清晰，有轮子、车轴、车篷等部件，结构精巧，轮辐清晰可见。
4. **大型伞盖（盖）**：车顶装有巨大的伞形车盖，是古代贵族出行时的遮阳避雨用具，象征身份与尊贵。
5. **铜质材料**：整体由青铜铸造，表面有铜绿（铜锈），颜色为青绿色带斑驳的锈斑，这是青铜器经久埋于地下形成的自然结果，也说明了它的年代久远。

**历史与艺术价值**：

- 秦始皇铜车马现藏于**西安秦始皇兵马俑博物馆**，是国家一级文物，也是中国青铜工艺的巅峰之作。
- 它是**现存年代最早、结构最完整、制作最精美的青铜车马模型**，比例约为真实车马的1:2，但结构完整，细节精致，体现了秦代青铜铸造技术的极高水平。
- 它不仅具有交通工具的功能象征，更是研究秦代车制、服饰、军事、礼仪和艺术的重要实物资料。

**总结**：

这张图展示的是**秦始皇铜车马（一号铜车马）的完整复原模型**，它代表了中国秦代宫廷车驾的真实样貌，是秦代青铜技术与雕塑艺术结合的杰作，也是世界范围内罕见的古代青铜车马文物。

它不是日常工具，而是**皇帝的象征性仪仗车**，用于彰显权力、体现礼制，是秦始皇陵陪葬品中最具代表性的文物之一。

---

如需进一步了解它的尺寸、出土位置、修复过程或与兵马俑的关系，也可以继续提问！
"""

成本优化¶

Token 计费¶

from tfrobot.brain.chain.llms import DashScope

# 设置价格（用于计费统计）
llm = DashScope(
    name="qwen-turbo", input_price=0.00024, output_price=0.00096  # ¥2.4/百万tokens（示例）  # ¥9.6/百万tokens（示例）
)

节省 Token 的技巧¶

使用 Turbo 模型：qwen-turbo 价格最低，适合简单任务
优化图片尺寸：使用合适的图片分辨率减少 Token 消耗
启用缓存：DashScope 支持 Prompt 缓存，减少重复计算
使用摘要模式：历史消息自动摘要

上下文管理¶

设置上下文窗口¶

from tfrobot.brain.chain.llms import DashScope

llm = DashScope(name="qwen-turbo", context_window=131072)  # 131K tokens

上下文压缩¶

当上下文超出限制时，Chain 会自动触发压缩：

from tfrobot.brain.chain.chain import Chain
from tfrobot.brain.chain.llms import DashScope
from tfrobot.schema.message.conversation.message_dto import TextMessage
from tfrobot.schema.users import BaseUser

# Chain 自动处理
llm = DashScope(name="qwen-turbo")
chain = Chain(llm=llm)

user = BaseUser(name="用户", uid="1")
user_input = TextMessage(content="很长的问题...会触发自动压缩", creator=user)
result = chain.run(current_input=user_input)

错误处理¶

常见错误及解决方案¶

错误场景	错误信息	解决方案
API Key 无效	Invalid API-key provided	检查环境变量 `DASHSCOPE_API_KEY`
上下文超限	Range of input length should be [1, N]	系统自动压缩上下文或手动缩短输入
图片下载超时	Download multimodal file timed out	检查 URL 可访问性，考虑使用 base64 编码
URL 缺少长度信息	Missing Content-Length of multimodal url	检查 URL 是否返回 Content-Length 头，或使用 base64
参数错误	InvalidParameter	检查模型参数是否在有效范围内

注意事项¶

错误响应机制：DashScope 在错误时返回 GenerationResponse 对象（包含 status_code 和 message），不抛出异常
网络重试：网络异常（超时、连接错误）会自动重试最多 3 次，使用指数退避策略
上下文压缩：当上下文超限时，Chain 层会自动触发压缩机制
多模态限制：某些模型不支持图片/视频/音频，会自动转换为文本提示

高级用法¶

流式输出¶

from tfrobot.brain.chain.llms import DashScope
from tfrobot.schema.message.conversation.message_dto import TextMessage
from tfrobot.schema.users import BaseUser

llm = DashScope(name="qwen-turbo", stream=True)
user = BaseUser(name="用户", uid="1")
user_input = TextMessage(content="测试问题", creator=user)

result = llm.complete(current_input=user_input)

阿里云 DashScope 使用指南¶

配置参数¶

核心参数¶

API 配置¶

互联网搜索¶

增量输出¶

工具调用¶

原生模式（推荐）¶

DashScope vs DashScopeWithTools¶

多模态支持¶

图片理解¶

成本优化¶

Token 计费¶

节省 Token 的技巧¶

上下文管理¶

设置上下文窗口¶

上下文压缩¶

错误处理¶

常见错误及解决方案¶

注意事项¶

高级用法¶

流式输出¶

相关文档¶