一、环境准备
1.1 安装框架
# 全功能安装（RAG/代码解释器/GUI支持）pip install -U "qwen-agent[rag,code_interpreter,python_executor,gui]"
# 简约安装版本pip install -U qwen-agent
1.2 模型服务配置
方法 1：官方服务
export DASHSCOPE_API_KEY='your-api-key'
方法 2：本地部署（vLLM 示例）
from vllm import LLM, SamplingParams
llm = LLM(model="Qwen2-7B-Chat")
二、核心功能开发
2.1 工具定义与使用
from qwen_agent.tools.base import BaseTool, register_toolimport json5
@register_tool('calculate')class Calculator(BaseTool):description = '基础运算计算器'parameters = [{'name': 'formula', 'type': 'string'}]def call(self, params: str) -> float:return eval(json5.loads(params)['formula'])
# 调用示例calc = Calculator()print(calc.call('{"formula": "(3 + 5) * 2"}'))# 输出 16.0
2.2 记忆功能实现
from qwen_agent.agents import Assistant
class HistoryAssistant(Assistant):def _postprocess_messages(self, messages):return messages[-10:]# 保留最近5轮对话
assistant = HistoryAssistant(llm={'model': 'qwen-max'})
三、完整示例开发
3.1 城市信息查询助手
from qwen_agent.agents import Assistantfrom qwen_agent.tools import BaseTool, register_toolimport requestsimport json5
@register_tool('city_info')class CityInfoTool(BaseTool):description = "城市基础信息查询"parameters = [{'name': 'name', 'type': 'string'}]def call(self, params):city = json5.loads(params)['name']response = requests.get(f"https://api.example.com/cities/{city}")return response.json()
# 配置助手assistant = Assistant(llm={'model': 'qwen-max'},function_list=['city_info','code_interpreter'],system_message="你是一个城市百科助手")
# 测试查询response = assistant.run([{'role': 'user', 'content': '上海有多少个行政区?'}])print(response[-1]['content'])
执行流程：
3.2 图像处理流程（集成代码解释器）
import urllibfrom qwen_agent.agents import Assistant
assistant = Assistant(function_list=['code_interpreter'],system_message="图像处理专家")
def process_image(prompt):messages = [{'role':'user', 'content': prompt}]for resp in assistant.run(messages):if 'function_call' in resp:code = resp['function_call']['arguments']exec(code)# 示例简化执行return resp[-1]['content']
process_image('将https://example.com/image.jpg的水平宽度扩大1.5倍')
四、进阶开发技巧
4.1 RAG 文档问答实现
from qwen_agent import retrieve
# 构建知识库retrieve.build_index('documents/')
class DocQA(Assistant):def _preprocess(self, query):contexts = retrieve.search(query)return f"根据文档：{contexts}\n回答：{query}"
qa = DocQA(llm={'model': 'qwen-max-longcontext'})
4.2 可视化界面集成
from qwen_agent.gui import WebUI
WebUI(assistant).launch(server_name='0.0.0.0', server_port=7860)
五、典型应用场景
5.1 客户服务机器人
class CustomerService(Assistant):def __init__(self):super().__init__(system_message="你是XX公司客服，回答范围限于产品功能和订单查询",function_list=[product_lookup, order_status])def _validate_query(self, query):if '价格' in query:return "具体产品价格请访问官网查询"return super()._validate_query(query)
5.2 数据分析助手
@register_tool('data_analysis')class DataAnalyzer:def call(self, params):df = pd.read_csv(params['file'])return df.describe().to_markdown()
assistant = Assistant(function_list=['data_analysis', 'code_interpreter'])
六、技术要点总结
动态流程控制
支持工具调用链、条件分支、循环处理等复杂逻辑
性能优化建议
✅ RAG 缓存机制提升高频查询响应
✅ 量化压缩降低部署资源消耗
✅ 设置执行超时保障系统稳定性
七、调试与优化
# 开启调试模式assistant = Assistant(verbose=True)
# 性能监控from qwen_agent.monitor import perf_counter
@perf_counterdef critical_function():pass
项目生态：每日更新迭代，建议定期查阅官方 GitHub 获取最新特性，已有数百个开源应用案例。
粤ICP备14082021号
免费POC，
零成本试错
