Home
Login
QwenLM/Qwen-AgentPlease refer to the latest official releases for information GitHub Homepage

Qwen 모델 기반의 지능형 에이전트 개발 프레임워크로, 함수 호출, 코드 인터프리터, RAG 및 브라우저 확장을 지원합니다.

Apache-2.0Python 9.7kQwenLMQwen-Agent Last Updated: 2025-06-18

Qwen-Agent 프로젝트 상세 소개

프로젝트 개요

Qwen-Agent는 첸원 대규모 언어 모델을 기반으로 한 지능형 에이전트 개발 프레임워크로, 명령어 준수, 도구 사용, 계획 및 기억 능력을 갖춘 LLM 애플리케이션 개발에 특화되어 있습니다. 이 프로젝트는 알리바바 첸원 팀에서 개발 및 유지 관리하며, 현재 첸원 채팅 서비스(Qwen Chat)의 백엔드 지원 역할을 합니다.

핵심 특징

1. 다기능 지능형 에이전트 지원

  • 브라우저 도우미 (Browser Assistant): 웹 페이지 탐색 및 조작 능력
  • 코드 인터프리터 (Code Interpreter): Python 코드 실행 및 분석
  • 맞춤형 도우미 (Custom Assistant): 개인화된 지능형 에이전트 맞춤 제작
  • RAG 검색 강화: 문서 질의응답 및 지식 검색
  • Chrome 확장: 브라우저 플러그인 형태의 지능형 도우미

2. 첨단 기술 통합

  • 함수 호출 (Function Calling): 도구 및 API 통합 지원
  • MCP 프로토콜 지원: 모델 컨텍스트 프로토콜 호환
  • 병렬 도구 호출: 다단계, 다회차 도구 사용
  • 추론 능력: QwQ-32B 등 추론 모델 통합

최신 업데이트 동향

  • 2025년 3월 18일: reasoning_content 필드 지원, 기본 함수 호출 템플릿 조정
  • 2025년 3월 7일: QwQ-32B 도구 호출 데모 추가, 병렬 및 다단계 호출 지원
  • 2024년 12월 3일: GUI를 Gradio 5로 업그레이드, Python 3.10+ 요구
  • 2024년 9월 18일: Qwen2.5-Math 데모 추가, 도구 통합 추론 능력 전시

설치 방법

안정 버전 설치

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 프로토콜 지원

모델 서비스 구성

방식 1: DashScope 서비스 사용

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

방식 2: 자체 배포 모델 서비스

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 그림 (이미지 생성) 서비스, 텍스트 설명을 입력하면 텍스트 정보를 기반으로 그림 URL을 반환합니다.'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': '원하는 이미지 내용에 대한 자세한 설명 (영어로)',
        '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 = '''사용자의 요청을 받으면 다음을 수행해야 합니다.
- 먼저 이미지를 그리고 이미지 URL을 얻습니다.
- 그런 다음 `request.get(image_url)` 코드를 실행하여 이미지를 다운로드합니다.
- 마지막으로 주어진 문서에서 이미지 작업을 선택하여 이미지를 처리합니다.
`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만 토큰 컨텍스트가 관련된 단일 "건초 더미에서 바늘 찾기" 스트레스 테스트에서 완벽한 성능을 보입니다.

BrowserQwen 브라우저 도우미

BrowserQwen은 Qwen-Agent를 기반으로 구축된 브라우저 도우미로, 웹 페이지 탐색, 조작 및 정보 추출 능력을 제공합니다.

기술 특징 및 장점

  1. 모듈화 설계: 원자 수준 컴포넌트, 확장 및 맞춤 제작 용이
  2. 다중 모델 지원: 첸원 시리즈 각 버전 모델 호환
  3. 풍부한 도구 생태계: 다양한 실용적인 도구 내장
  4. 유연한 배포: 클라우드 서비스 및 로컬 배포 지원
  5. 활발한 유지 관리: 지속적인 업데이트 및 기능 강화

관련 리소스 링크

요약

Qwen-Agent는 강력하고 사용하기 쉬운 지능형 에이전트 개발 프레임워크로, 개발자에게 복잡한 LLM 애플리케이션을 구축할 수 있는 완벽한 도구 체인을 제공합니다. 간단한 챗봇이든 복잡한 다기능 지능형 도우미이든 이 프레임워크를 통해 빠르게 구현하고 배포할 수 있습니다.

Star History Chart