[AI] VLLM qwen3(tool_calls) web서버 사용 방법 ( 리눅스 )

vLLM은 대형 언어 모델(LLM)의 추론 및 서빙을 효율적이고 고속으로 처리할 수 있는 오픈소스 라이브러리입니다.

 

특징

• 고성능 추론 및 서빙
• OpenAI 호환 API 서버
• 다양한 모델 지원
• 하드웨어 및 분산 추론 지원

vllm web 서버 생성

먼저 로컬 모델이나 허깅페이스에서 사용할 모델을 다운로드하거나 정해야 한다.

chat-template ./qwen3_nonthinking.jinja은 https://qwen.readthedocs.io/en/latest/deployment/vllm.html 에서 다운로드할 수 있다. qwen3의 nothink를 위한 chat template이다 think를 사용하고 싶으면 안 해도 된다.

vllm serve 로컬 모델경로 or 허깅페이스 가능  --served-model-name Qwen3 --chat-template ./qwen3_nonthinking.jinja --enable-auto-tool-choice --tool-call-parser hermes --reasoning-parser qwen3 --tensor-parallel-size 2 --host 0.0.0.0 --port 9507 --gpu-memory-utilization=0.7 --disable-log-requests

 

localhost:9507/docs에 접근하면 생성된 api를 확인할 수 있다. FastAPI로 생성된다.

 

1. vllm serve

• 설명: vllm serve는 vLLM 서버를 시작하는 명령어입니다. 이를 통해 모델 추론 및 서빙을 로컬에서 실행할 수 있습니다.

2. served-model-name Qwen3

• 설명: 서빙할 모델의 이름을 지정하는 옵션입니다. 여기서는 "Qwen3"이라는 모델을 서빙하도록 설정하고 있습니다. 이 모델은 로컬 모델 경로 또는 Hugging Face 모델 허브에서 불러올 수 있습니다.

3. chat-template ./qwen3_nonthinking.jinja (선택사항)

• 설명: 모델의 채팅 응답 템플릿을 지정하는 옵션입니다. ./qwen3_nonthinking.jinja는 Jinja2 템플릿 파일로, 모델이 응답을 생성할 때 사용할 포맷을 정의하는 파일입니다. 이 템플릿을 통해 모델의 응답 방식이나 구조를 세부적으로 조정할 수 있습니다. https://qwen.readthedocs.io/en/latest/deployment/vllm.html

4. enable-auto-tool-choice

• 설명: 자동 툴 선택 기능을 활성화하는 옵션입니다. 이 옵션이 활성화되면, 모델이 특정 작업을 수행하기 위해 필요한 툴을 자동으로 선택하고 실행할 수 있습니다.

5. tool-call-parser hermes

• 설명: 툴 호출을 처리하는 파서(parser)를 지정하는 옵션입니다. hermes는 툴 호출을 분석하고 처리하는 데 사용되는 파서로, 툴과의 상호작용을 적절하게 다룹니다.

6. reasoning-parser qwen3

• 설명: 모델의 추론을 처리하는 파서를 설정하는 옵션입니다. qwen3는 해당 모델에 적합한 추론 파서를 지정하며, 모델이 문제를 해결하는 방식이나 사고 과정을 관리합니다.

7. tensor-parallel-size 2

• 설명: 텐서 병렬 처리의 크기를 설정하는 옵션입니다. 텐서 병렬화는 대형 모델을 여러 GPU에 분산하여 처리하는 기술입니다. 2는 두 개의 GPU에 걸쳐 모델을 분산 처리하는 설정입니다. 이렇게 하면 메모리 제한을 극복하면서 더 큰 모델을 효율적으로 사용할 수 있습니다.

8. host 0.0.0.0

• 설명: 서버가 실행될 호스트 주소를 지정하는 옵션입니다. 0.0.0.0은 모든 IP 주소에서 서버에 접근할 수 있도록 설정하는 것입니다. 일반적으로 로컬 네트워크에서 여러 장치가 이 서버에 접근할 수 있도록 할 때 사용합니다.

9. port 9507

• 설명: 서버가 사용할 포트를 설정하는 옵션입니다. 9507은 서버가 요청을 수신할 포트 번호입니다. 이 포트 번호로 클라이언트가 접속하게 됩니다.

10. gpu-memory-utilization=0.7

• 설명: GPU의 메모리 사용 비율을 설정하는 옵션입니다. 0.7은 GPU의 메모리의 70%만 사용하도록 설정하여, 메모리 오버로드를 방지하고 다른 작업도 동시에 수행할 수 있도록 합니다.

11. disable-log-requests

• 설명: 요청에 대한 로그 기록을 비활성화하는 옵션입니다. 이 옵션을 사용하면 서버가 들어오는 요청을 기록하지 않게 되어, 로그 파일이 축적되는 것을 방지할 수 있습니다. 이는 성능을 최적화하는 데 유용할 수 있습니다.

호출 방법

• from openai import OpenAI를 사용하는 방법

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",  # 로컬에서 vLLM이면 아무 문자열이나 가능
    base_url="http://localhost:9507/v1",  # vLLM 호스트 주소
)
models  = client.models.list() # 모델리스트
print(models) # 모델리스트 확인
print(models.data[0].id) # 특정 모델 확인

chat_response = client.chat.completions.create(
    model="Qwen3",
    messages=[{"role": "user", "content": "지구에 대해 알려줘"}],

    temperature=0.7,
    top_p=0.8,
    presence_penalty=1.5,

)
print(chat_response.choices[0].message.content)

 

• from langchain_openai import ChatOpenAI를 사용한 방법

stream을 사용하기 싫으면 streaming와 callbacks를 제거해 주면 된다.

랭체인과 사용하려면 이방법이 제일 쉬운 것 같다.

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from langchain.callbacks.streaming_stdout import StreamingStdOutCallbackHandler

llm = ChatOpenAI(
    model="Qwen3",
    base_url="http://localhost:9507/v1",
    api_key="EMPTY",
    streaming=True,
    callbacks=[StreamingStdOutCallbackHandler()]  # 스트리밍 핸들러 등록
)

response = llm.invoke([HumanMessage(content="지구에 대해 설명해줘")])

참조

https://qwen.readthedocs.io/en/latest/framework/function_call.html#vllm
https://docs.vllm.ai/en/stable/features/tool_calling.html#required-function-calling
https://docs.vllm.ai/en/stable/features/tool_calling.html
https://langchain-ai.github.io/langgraph/agents/models/#disable-streaming
https://qwen.readthedocs.io/en/latest/deployment/vllm.html#thinking-non-thinking-modes