通义千问集成

OpenAI/Claude 虽强，但国内生产环境用它们要折腾代理、要付美元。阿里云的**通义千问（Qwen）**是国内首选之一：直连无需代理、人民币结算、工具调用稳定、有免费额度。本章讲怎么接进 LangGraph。

一、通义千问简介

通义千问是阿里达摩院的大模型系列，通过阿里云**灵积（DashScope）**平台对外服务。常用模型：

模型	特点	适用
qwen-plus	性价比之王，工具调用稳	智能体首选
qwen-turbo	最快最便宜	简单任务/高并发
qwen-max	旗舰，最强	复杂推理
qwen-long	长上下文（千万级）	长文档分析

新手做智能体推荐 qwen-plus：能力和 gpt-4o-mini 同档，价格更低。

二、安装与配置

2.1 安装

通义千问的 LangChain 集成在 langchain-community 里，依赖阿里官方 SDK dashscope：

pip install langchain-community dashscope -i https://pypi.tuna.tsinghua.edu.cn/simple

2.2 获取 API Key

1. 登录阿里云百炼/DashScope 控制台：https://dashscope.console.aliyun.com
2. 开通服务（新用户有免费额度）。
3. 创建 API-KEY，复制保存。

2.3 配置环境变量

# Windows
setx DASHSCOPE_API_KEY "sk-你的key"

# macOS / Linux
export DASHSCOPE_API_KEY="sk-你的key"

ChatTongyi 会自动读 DASHSCOPE_API_KEY。设完重开终端。

三、ChatTongyi 基础用法

3.1 最简调用

from langchain_community.chat_models import ChatTongyi
from langchain_core.messages import HumanMessage

llm = ChatTongyi(model="qwen-plus", temperature=0)
resp = llm.invoke([HumanMessage(content="你好，用一句话介绍自己")])
print(resp.content)

3.2 常用参数

llm = ChatTongyi(
    model="qwen-plus",
    temperature=0,        # 0-1
    max_tokens=1024,      # 最大输出
    # streaming=True,     # 默认就支持 stream()
)

注意：ChatTongyi 不用 base_url，国内直连即可。

3.3 流式输出

for chunk in llm.stream([HumanMessage(content="写一首七言绝句")]):
    print(chunk.content, end="", flush=True)

四、工具调用

通义千问支持 OpenAI 风格的工具调用，bind_tools 直接可用：

from langchain_core.tools import tool

@tool
def add(a: float, b: float) -> float:
    """两数相加。"""
    return a + b

@tool
def get_weather(city: str) -> str:
    """查询城市天气。"""
    return {"北京": "晴 25°C"}.get(city, "未知")

llm = ChatTongyi(model="qwen-plus", temperature=0)
llm_with_tools = llm.bind_tools([add, get_weather])

resp = llm_with_tools.invoke("北京天气？再算 3+5")
print(resp.tool_calls)
# [{'name': 'get_weather', 'args': {'city': '北京'}},
#  {'name': 'add', 'args': {'a': 3, 'b': 5}}]

实测 qwen-plus 的工具调用准确率和 gpt-4o-mini 相当，多工具场景下偶有选错，但比小模型强很多。

五、qwen-long 长上下文

qwen-long 支持千万级 token 上下文，适合长文档问答。用法略特殊：先上传文件拿到 file-id，再引用：

from langchain_community.chat_models import ChatTongyi

llm = ChatTongyi(model="qwen-long")
# 简化示例：实际要先调 dashscope 文件上传接口拿 fileid
resp = llm.invoke("总结这个文档", files=[{"file_id": "filexxx"}])

新手用 qwen-plus 即可，长文档场景再上 qwen-long。

六、在 LangGraph 中构建 ReAct

把通义千问塞进 create_react_agent，几行就是一个国产智能体：

from langchain_community.chat_models import ChatTongyi
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage
from langgraph.prebuilt import create_react_agent

@tool
def add(a: float, b: float) -> float:
    """两数相加。"""
    return a + b

@tool
def multiply(a: float, b: float) -> float:
    """两数相乘。"""
    return a * b

@tool
def get_weather(city: str) -> str:
    """查询城市天气，支持北京/上海/广州。"""
    data = {"北京": "晴 25°C", "上海": "多云 28°C", "广州": "雨 31°C"}
    return data.get(city, f"{city} 未知")

agent = create_react_agent(
    model=ChatTongyi(model="qwen-plus", temperature=0),
    tools=[add, multiply, get_weather],
    prompt="你是中文助手，按需调用工具，回答用简体中文。",
)

result = agent.invoke({
    "messages": [HumanMessage(content="查广州天气，然后算 25 乘以 4")]
})
print(result["messages"][-1].content)

预期：通义千问先调 get_weather，再调 multiply，最后汇总回答。

七、完整可运行示例

下面这个脚本演示普通对话、流式、工具调用三件套：

import os
from dotenv import load_dotenv
from langchain_community.chat_models import ChatTongyi
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.prebuilt import create_react_agent

load_dotenv()   # 从 .env 读 DASHSCOPE_API_KEY

# 1. 基础对话
llm = ChatTongyi(model="qwen-plus", temperature=0)
print("=== 基础对话 ===")
print(llm.invoke([HumanMessage(content="用一句话介绍 LangGraph")]).content)

# 2. 流式
print("\n=== 流式 ===")
for chunk in llm.stream([HumanMessage(content="写一句关于编程的诗")]):
    print(chunk.content, end="", flush=True)
print()

# 3. 工具调用 + ReAct
@tool
def add(a: float, b: float) -> float:
    """两数相加。"""
    return a + b

@tool
def get_weather(city: str) -> str:
    """查城市天气，支持北京/上海。"""
    return {"北京": "晴 25°C", "上海": "多云 28°C"}.get(city, "未知")

print("\n=== ReAct 智能体 ===")
agent = create_react_agent(
    llm, [add, get_weather],
    prompt="你是中文助手，按需调工具，简体中文回答。",
)
r = agent.invoke({"messages": [HumanMessage(content="上海天气如何？再算 100+200")]})
print(r["messages"][-1].content)

八、常见踩坑

1. 模型名变更

阿里时不时会更新模型名/下线旧模型。比如早期的 qwen-7b-chat 已下线。用 qwen-plus / qwen-turbo / qwen-max 这类"别名"比写带版本号的稳定。模型下线会报 Model not found，去 DashScope 文档查最新名。

2. 限流

免费额度/QPS 有限，高并发会报 429。对策：

• 在 DashScope 后台申请提升 QPS。
• 代码里加重试 + 退避（tenacity 库）。
• 高峰用 qwen-turbo（限流更宽松）。

3. 国内直连无需代理

新手常犯的错：照搬 OpenAI 教程配了一堆代理，结果反而连不上。通义千问国内直连，别设 http_proxy 环境变量，否则可能把请求绕到国外再回来，慢且易断。

4. 工具调用偶尔不触发

qwen-turbo 工具调用能力弱于 qwen-plus，复杂工具可能不触发。做智能体务必用 qwen-plus 及以上。

5. dashscope 版本

langchain-community 依赖 dashscope，老版本 dashscope 不支持工具调用。装最新：

pip install -U dashscope -i https://pypi.tuna.tsinghua.edu.cn/simple

九、小结

• 通义千问国内直连、人民币结算、工具调用稳，是国内生产首选。
• ChatTongyi(model="qwen-plus") 即可，自动读 DASHSCOPE_API_KEY。
• 在 LangGraph 里和 create_react_agent 配合，几行搭一个国产智能体。
• 踩坑：模型名变更、限流、别配代理、用 qwen-plus 起步。

另一家国产厂商智谱下一章讲：智谱GLM集成。