Qwen-Agent 項目詳細介紹

項目概述

Qwen-Agent 是一個基於千問大語言模型的智能體開發框架，專門用於開發具備指令遵循、工具使用、規劃和記憶能力的 LLM 應用程式。該項目由阿里巴巴千問團隊開發維護，目前作為千問聊天服務 (Qwen Chat) 的後端支撐。

核心特性

1. 多功能智能體支持

瀏覽器助手 (Browser Assistant): 網頁瀏覽和操作能力
代碼解釋器 (Code Interpreter): Python 代碼執行和分析
自定義助手 (Custom Assistant): 個性化智能體定制
RAG 檢索增強: 文件問答和知識檢索
Chrome 擴展: 瀏覽器插件形式的智能助手

2. 先進技術集成

函數調用 (Function Calling): 支持工具和 API 集成
MCP 協議支持: 模型上下文協議兼容
並行工具調用: 多步驟、多輪次工具使用
推理能力: 集成 QwQ-32B 等推理模型

安裝方式

穩定版本安裝

pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
# 或最小安裝
pip install -U qwen-agent

開發版本安裝

git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./"[gui,rag,code_interpreter,mcp]"

可選依賴說明

[gui]: Gradio 圖形界面支持
[rag]: RAG 檢索增強功能
[code_interpreter]: 代碼解釋器功能
[mcp]: MCP 協議支持

模型服務配置

方式一：使用 DashScope 服務

llm_cfg = {
    'model': 'qwen-max-latest',
    'model_server': 'dashscope',
    # 'api_key': 'YOUR_DASHSCOPE_API_KEY',
    'generate_cfg': {
        'top_p': 0.8
    }
}

方式二：自部署模型服務

llm_cfg = {
    'model': 'Qwen2.5-7B-Instruct',
    'model_server': 'http://localhost:8000/v1',
    'api_key': 'EMPTY',
}

核心組件架構

基礎組件

BaseChatModel: LLM 基礎類，支持函數調用
BaseTool: 工具基礎類，可擴展自定義功能
Agent: 智能體基礎類，支持繼承定制

高級組件

Assistant: 通用助手智能體
FnCallAgent: 函數調用智能體
ReActChat: 推理行動對話智能體

實際應用示例

創建自定義工具智能體

import pprint
import urllib.parse
import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
from qwen_agent.utils.output_beautify import typewriter_print

# 步驟1: 添加自定義工具
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Detailed description of the desired image content, in English',
        'required': True
    }]
    
    def call(self, params: str, **kwargs) -> str:
        prompt = json5.loads(params)['prompt']
        prompt = urllib.parse.quote(prompt)
        return json5.dumps(
            {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
            ensure_ascii=False)

# 步驟2: 配置 LLM
llm_cfg = {
    'model': 'qwen-max-latest',
    'model_server': 'dashscope',
    'generate_cfg': {
        'top_p': 0.8
    }
}

# 步驟3: 創建智能體
system_instruction = '''After receiving the user's request, you should:
- first draw an image and obtain the image url,
- then run code `request.get(image_url)` to download the image,
- and finally select an image operation from the given document to process the image.
Please show the image using `plt.show()`.'''

tools = ['my_image_gen', 'code_interpreter']
files = ['./examples/resource/doc.pdf']
bot = Assistant(llm=llm_cfg,
                system_message=system_instruction,
                function_list=tools,
                files=files)

# 步驟4: 運行智能體聊天
messages = []
while True:
    query = input('\nuser query: ')
    messages.append({'role': 'user', 'content': query})
    response = []
    response_plain_text = ''
    print('bot response:')
    for response in bot.run(messages=messages):
        response_plain_text = typewriter_print(response, response_plain_text)
    messages.extend(response)

啟動 Web UI 界面

from qwen_agent.gui import WebUI
WebUI(bot).run()

MCP 協議集成

MCP 伺服器配置示例

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    },
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "test.db"
      ]
    }
  }
}

依賴環境要求

Node.js (最新版本)
uv 0.4.18 或更高版本
Git
SQLite

RAG 文檔問答能力

項目提供了快速 RAG 解決方案，以及針對超長文檔的競爭性智能體，在兩個具有挑戰性的基準測試中表現優於原生長上下文模型，並在涉及 100萬 token 上下文的單針"大海撈針"壓力測試中表現完美。

BrowserQwen 瀏覽器助手

BrowserQwen 是基於 Qwen-Agent 構建的瀏覽器助手，提供網頁瀏覽、操作和信息提取能力。

技術特點與優勢

模塊化設計: 原子級組件，便於擴展和定制
多模型支持: 兼容千問系列各版本模型
豐富的工具生態: 內置多種實用工具
靈活部署: 支持雲服務和本地部署
活躍維護: 持續更新和功能增強

總結

Qwen-Agent 是一個功能強大、易於使用的智能體開發框架，為開發者提供了構建複雜 LLM 應用的完整工具鏈。無論是簡單的聊天機器人還是複雜的多功能智能助手，都可以通過該框架快速實現和部署。

Qwen-Agent