Qwen-Agent: Descrição Detalhada do Projeto

Visão Geral do Projeto

Qwen-Agent é um framework de desenvolvimento de agentes inteligentes baseado no modelo de linguagem grande Qwen, especificamente projetado para desenvolver aplicações LLM com capacidades de seguir instruções, usar ferramentas, planejar e memorizar. Este projeto é desenvolvido e mantido pela equipe Qwen da Alibaba e atualmente serve como suporte de backend para o serviço de chat Qwen (Qwen Chat).

Principais Características

1. Suporte a Agentes Multifuncionais

• Assistente de Navegador (Browser Assistant): Capacidade de navegação e operação na web
• Intérprete de Código (Code Interpreter): Execução e análise de código Python
• Assistente Personalizado (Custom Assistant): Personalização de agentes inteligentes
• Aprimoramento de Recuperação RAG: Perguntas e respostas sobre documentos e recuperação de conhecimento
• Extensão Chrome: Assistente inteligente na forma de um plugin de navegador

2. Integração de Tecnologia Avançada

• Chamada de Função (Function Calling): Suporte para integração de ferramentas e APIs
• Suporte ao Protocolo MCP: Compatibilidade com o protocolo de contexto do modelo
• Chamada de Ferramentas Paralelas: Uso de ferramentas em várias etapas e rodadas
• Capacidade de Inferência: Integração de modelos de inferência como QwQ-32B

Últimas Atualizações

• 18 de março de 2025: Suporte ao campo reasoning_content, ajuste do modelo de chamada de função padrão
• 7 de março de 2025: Adição da demonstração de chamada de ferramenta QwQ-32B, suporte para chamadas paralelas e em várias etapas
• 3 de dezembro de 2024: Atualização da GUI para Gradio 5, requer Python 3.10+
• 18 de setembro de 2024: Adição da demonstração Qwen2.5-Math, mostrando a capacidade de inferência de integração de ferramentas

Instalação

Instalação da Versão Estável

pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
# Ou instalação mínima
pip install -U qwen-agent

Instalação da Versão de Desenvolvimento

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

Descrição das Dependências Opcionais

• [gui]: Suporte à interface gráfica Gradio
• [rag]: Funcionalidade de aprimoramento de recuperação RAG
• [code_interpreter]: Funcionalidade de intérprete de código
• [mcp]: Suporte ao protocolo MCP

Configuração do Serviço de Modelo

Método 1: Usando o Serviço DashScope

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

Método 2: Serviço de Modelo Auto-Hospedado

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

Arquitetura dos Componentes Principais

Componentes Básicos

• BaseChatModel: Classe base LLM, suporta chamada de função
• BaseTool: Classe base de ferramenta, extensível para funcionalidade personalizada
• Agent: Classe base de agente inteligente, suporta personalização por herança

Componentes Avançados

• Assistant: Agente inteligente assistente genérico
• FnCallAgent: Agente inteligente de chamada de função
• ReActChat: Agente inteligente de diálogo de ação de inferência

Exemplos de Aplicação Prática

Criar um Agente Inteligente de Ferramenta Personalizada

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

# Passo 1: Adicionar ferramenta personalizada
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    description = 'Serviço de pintura AI (geração de imagem), insira a descrição do texto e retorne o URL da imagem desenhada com base nas informações do texto.'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Descrição detalhada do conteúdo da imagem desejada, em inglês',
        '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)

# Passo 2: Configurar LLM
llm_cfg = {
    'model': 'qwen-max-latest',
    'model_server': 'dashscope',
    'generate_cfg': {
        'top_p': 0.8
    }
}

# Passo 3: Criar agente inteligente
system_instruction = '''Depois de receber a solicitação do usuário, você deve:
- primeiro desenhar uma imagem e obter o url da imagem,
- então executar o código `request.get(image_url)` para baixar a imagem,
- e finalmente selecionar uma operação de imagem do documento fornecido para processar a imagem.
Por favor, mostre a imagem usando `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)

# Passo 4: Executar o chat do agente inteligente
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)

Iniciar a Interface Web UI

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

Integração do Protocolo MCP

Exemplo de Configuração do Servidor 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"
      ]
    }
  }
}

Requisitos do Ambiente de Dependência

• Node.js (versão mais recente)
• uv 0.4.18 ou superior
• Git
• SQLite

Capacidade de Perguntas e Respostas de Documentos RAG

O projeto fornece uma solução RAG rápida, bem como um agente inteligente competitivo para documentos superlongos, que supera os modelos de contexto de crescimento nativo em dois benchmarks desafiadores e tem um desempenho perfeito em um teste de estresse de "agulha no palheiro" de tiro único envolvendo um contexto de 1 milhão de tokens.

Assistente de Navegador BrowserQwen

BrowserQwen é um assistente de navegador construído com base no Qwen-Agent, fornecendo recursos de navegação, operação e extração de informações na web.

Características e Vantagens Técnicas

1. Design Modular: Componentes de nível atômico, fáceis de expandir e personalizar
2. Suporte a Vários Modelos: Compatível com várias versões da série Qwen
3. Rico Ecossistema de Ferramentas: Várias ferramentas práticas integradas
4. Implantação Flexível: Suporte para serviços de nuvem e implantação local
5. Manutenção Ativa: Atualizações e aprimoramentos de recursos contínuos

Links de Recursos Relacionados

• Repositório GitHub: https://github.com/QwenLM/Qwen-Agent
• Documentação Oficial: https://qwen.readthedocs.io/
• Experiência Online: https://chat.qwen.ai/
• Blog Técnico: https://qwenlm.github.io/blog/qwen-agent-2405/
• Hugging Face: https://huggingface.co/Qwen
• ModelScope: https://modelscope.cn/organization/qwen

Resumo

Qwen-Agent é um framework de desenvolvimento de agentes inteligentes poderoso e fácil de usar, fornecendo aos desenvolvedores uma cadeia de ferramentas completa para construir aplicações LLM complexas. Seja um chatbot simples ou um assistente inteligente multifuncional complexo, ele pode ser rapidamente implementado e implantado por meio desta estrutura.