Claude Code + Ollama + Qwen2.5-coder

 

 

Anthropic이 Claude Code를 공개했습니다. 이전까지만 해도 Claude 모델의 API를 이용하도록 되어 있던 것이었습니다. 최근 비슷한 방식으로 사용할 수 있는 오픈소스 도구가 많이 나오면서 위기를 느끼고 기존의 개발자들이 자기들의 생태계에 계속 머물도록 하려는 의도로 공개한 것으로 판단되고 있습니다. 

 

이번 글에서는 Claude Code와 로컬 PC에서 동작하는 코딩 전용 모델을 연결해서 사용하는 방법을 정리해 보겠습니다. 즉, Claude Code + Ollama + Qwen2.5-Coder 연동입니다. 

 

---

Claude Code + Ollama + Qwen2.5-coder

1.개요

 

전반적인 구성은 다음과 같습니다. 

• Ollama : 로컬 PC에서 동작할 수 있는 AI 추론 엔진 및 프레임워크. 최근엔 개인용으로 가장 많이 사용 중인 듯...
• Qwen2.5-Coder : 경량이지만 MoE 기법이 적용되어 높은 성능을 보여주는 코딩 모델
• Claude Code : Anthropic에서 공개한 터미널 기반의 AI 코딩 에이전트

 

2.환경 구성

 

1️⃣ Ollama 설치 (링크)

# ollama 설치
curl -fsSL https://ollama.com/install.sh | sh

# 버전 확인
ollama --version

 

 

2️⃣ 로컬 코딩 LLM 설치 (Qwen2.5-coder)

 

소비자 GPU에서 가장 가성비 높다는 Qwen2.5-coder를 이용합니다. 아래와 같이 하면 기본은 qwen2.5-coder:latest 버전(7B, 4.7GB 용량)이 다운로드되고 동작됩니다. 그런데 이 모델의 경우, Context Window 사이즈가 32K로 생각보다 크지 않습니다. 

# qwen2.5-coder
ollama run qwen2.5-coder

(ollama) sol@solOffice:~/ollama$ ollama run qwen2.5-coder
pulling manifest 
pulling 60e05f210007: 100% ▕██████████████████▏ 4.7 GB                         
pulling 66b9ea09bd5b: 100% ▕██████████████████▏   68 B                         
pulling 1e65450c3067: 100% ▕██████████████████▏ 1.6 KB                         
pulling 832dd9e00a68: 100% ▕██████████████████▏  11 KB                         
pulling d9bb33f27869: 100% ▕██████████████████▏  487 B                         
verifying sha256 digest 
writing manifest 
success 
>>> 안녕
안녕하세요! 어떻게 도와드릴 수 있을까요?

 

 

주의사항)

처음 설치할 때 sudo를 이용하면 ollama의 모델 path가 사용자로 실행했을 때와 달라집니다. 결과적으로 앞서 커맨드로 다운받은 게 있는데 일반 사용자 계정으로 실행하면 다시 Pull 해 오는 현상이 발생합니다. 그러니 받은 것을 아래 폴더에 옮겨두던가 아니면 심볼릭 Path를 만들던가 혹은 환경 변수 OLLAMA_MODELS를 시스템에 지정하고 사용해야 합니다. 

• sudo 실행 시 : /usr/share/ollama/.ollama/models
• 일반 사용자 실행 시 : ~/.ollama/models

 

3️⃣ Claude Code 설치 (링크)

# 클로드 코드 설치
$ curl -fsSL https://claude.ai/install.sh | bash


Setting up Claude Code...
✔ Claude Code successfully installed!        
  Version: 2.1.31
  Location: ~/.local/bin/claude

  Next: Run claude --help to get started

✅ Installation complete!

 

 

4️⃣ Claude Code와 Ollama 연결

 

Claude Code에서 Ollama를 연동하기 위해서는 모델의 PATH를 명시적으로 환경 변수에 설정 해야 합니다. 이는 로컬 LLM 설치 부분에서 이미 언급한 바가 있습니다.  

export OLLAMA_MODELS=~/.ollama/models

 

 

3.Claude Code로 Ollama 모델 연동 테스트

 

아주 단순하게 Claude Code에서 Ollama 모델을 로딩해서 처리하는 예시를 진행합니다. 

claude --model qwen2.5-coder

 

Claude Code CLI 화면을 그대로 이용할 수 있습니다. 기존 상용 모델 대신 로컬에서 돌아가는 모델로 대체된 상태로 말이죠.

 

4.Claude Code를 이용한 코드 디버깅 테스트

 

단일 html 프로그램을 생성하고 이 코드의 내용을 분석해서 발생할 수 있는 오류를 찾아내 달라고 요청해 보겠습니다. 작업은 vscode의 터미널에서 claude를 실행하고 진행합니다. 아래 이미지의 윗 부분은 지시어 문장이고, 그 아래 부분이 분석 결과입니다. 

참고) 사실 시행착오가 있었는데, 첫 시도는 다음과 같았습니다. '분석'을 시켜야 하는데 지시를 충분히 하지 못해서 Claude Code가 '실행'을 해 버린 것이었죠. 즉, Claude에게 어떤 일을 시킬 것인지 정의해 주는 것도 중요하지만, 어떻게 동작할지 정해주는 것도 아주 중요하다는 걸 깨달았습니다. 

 

 

참고) Anthropic SDK를 이용한 Ollama 호출 (테스트)

 

이 내용은 Claude Code와는 상관없지만, 로컬에 설치된 Ollama에서 로딩한 AI 모델을 Python에서 호출하는 방식은 Anthropic python SDK를 이용하는 방식이 있습니다. LM Studio에서도 이런 기능을 제공했었죠. 여기서는 간단히 어떤 식으로 진행되는지만 따라가 보겠습니다. 

 

Anthropic 패키지 설치

$ pip install anthropic

 

 

Anthropic 환경변수 설정

 

Anthropic SDK를 이용해 Ollama 서비스를 호출하기 위해서는 BASE_URL과 Auth 값이 필요합니다. 다음과 설정합니다. AUTH 값은 다른 값을 써도 되는 것 같습니다. 그리고 환경정보 설정없이 직접 코드에서 하드코딩해도 됩니다. 하지만 설정하는 것이 코드 보안상 유리할 겁니다. 

# 환경 정보 설정
export ANTHROPIC_BASE_URL=http://localhost:11434
export ANTHROPIC_AUTH=ollama

 

3) Anthropic SDK 테스트 

 

가장 간단한 코드 예시입니다. (접속할 ollama 정보는 직접 넣는 방식으로 함)

from anthropic import Anthropic

client = Anthropic(
    api_key="ollama",  
    base_url="http://localhost:11434"
)

response = client.messages.create(
    model="qwen2.5-coder",
    max_tokens=1024,
    temperature=0.2,
    messages=[
        {
            "role": "user",
            "content": "Write a Python async websocket echo server."
        }
    ],
)

print(response.content[0].text)

 

실행 결과는 다음과 같습니다. 

Certainly! Below is an example of an asynchronous WebSocket echo server using the `websockets` library in Python. This server will receive messages from clients and send them back as responses.

First, make sure you have the `websockets` library installed. You can install it using pip:

```sh
pip install websockets
```

Now, here's the code for the echo server:

```python
import asyncio
import websockets

async def echo(websocket, path):
    async for message in websocket:
        await websocket.send(message)

start_server = websockets.serve(echo, "localhost", 8765)

asyncio.get_event_loop().run_until_complete(start_server)
asyncio.get_event_loop().run_forever()
```

... 이하 생략 ...

 

---

 

이번 글에서는 Claude Code를 설치하고 로컬 LLM과 연결하는 것까지 해 봤습니다. Claude Code도 Ollama도 익숙치 않아서 공부를 해야하는터라 이번에는 여기까지만 정리하고 이후는 사용해 보면서 기록할만한 것이 있으면 또 올리도록 하겠습니다. ^^;