Kanana-2 Open Source로 에이전트 만들기 – 실무 활용 시나리오 & 코드 예시

Kanana-2 Open Source 시스템 아키텍처

어떤 프로젝트에 Kanana-2 Open Source를 쓰면 좋을까?

카카오 기술블로그와 관련 기사들을 보면, Kanana-2는 에이전트형 서비스를 강하게 의식하고 설계된 모델입니다.

대표적으로 이런 프로젝트에 어울려요.

  1. 도구 호출 기반 에이전트
    • 예: “조직문화 면담 요약 → 위험 키워드 분석 → Jira 이슈 자동 생성” 같은 파이프라인
    • Kanana-2 Instruct/Thinking에게 “이 상황에서 사용할 함수 이름과 파라미터를 JSON으로 반환해 줘” 같은 패턴을 학습시키기 좋습니다.
  2. 한국어 중심 업무 자동화
    • 예: 공공기관/에너지 회사/내부 시스템의 Korean-heavy 문서 요약, Q&A, 보고서 작성 도우미
    • 한국어 질의 응답 성능이 강점으로 언급되므로, 사내 데이터 + RAG와 결합하기 편합니다.
  3. 연구/실험용 국산 LLM 플랫폼
    • MoE, MLA, 긴 컨텍스트 등 최신 구조를 한국어 데이터와 함께 실험하고 싶은 연구자에게도 유용합니다.

모델 선택 가이드 – Base / Instruct / Thinking

kanana-2 open source huggingface page image

Hugging Face 페이지 기준으로, Kanana-2-30B-A3B 계열은 이렇게 나뉩니다.

  • Base
    • “원석”에 가까운 모델
    • 나만의 도메인(예: 조직문화, 사내 매뉴얼)에 맞게 파인튜닝하고 싶은 경우에 적합
  • Instruct
    • 우리가 흔히 쓰는 “대화형 지시 응답”에 맞춰 튜닝된 버전
    • 프롬프트만 잘 주면 바로 챗봇/도우미로 쓰기 좋음
  • Thinking
    • 이름 그대로 추론(Thinking)에 조금 더 무게를 둔 모델
    • 복잡한 플로우, 단계별 Reasoning, 도구 호출이 엮인 워크플로우에서 강점

실무용 한 줄 추천

  • “당장 챗봇/에이전트 PoC를 만들고 싶다” → Instruct
  • “도메인 특화 + 연구 + 파인튜닝” → Base
  • “툴콜링 + Reasoning 테스트를 집중적으로 하고 싶다” → Thinking

Python + Hugging Face로 Kanana-2 Open Source 맛보기

下面的代码显示了 개념 예시용이에요. 실제로는 GPU 자원과 메모리 고려가 필요합니다.

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

MODEL_ID = "kakaocorp/kanana-2-30b-a3b-thinking"  # Kanana-2 오픈소스 thinking 예시

tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    torch_dtype=torch.bfloat16,
    device_map="auto"  # 적절한 GPU/CPU 환경에 맞게 조정
)

def ask_kanana(prompt: str, max_tokens: int = 512) -> str:
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    with torch.no_grad():
        output = model.generate(
            **inputs,
            max_new_tokens=max_tokens,
            do_sample=True,
            temperature=0.7,
        )
    return tokenizer.decode(output[0], skip_special_tokens=True)

if __name__ == "__main__":
    prompt = (
        "당신은 에이전틱 AI 연구를 돕는 조수입니다. "
        "Kanana-2 오픈소스 모델의 특징을 한국어로 5줄 이내로 요약해 주세요."
    )
    print(ask_kanana(prompt))

이 정도만으로도 “Kanana-2 Open Source가 어떤 톤과 스타일로 답하는지” 감을 잡을 수 있어요.
실제 서비스에서는 반드시

  • 프롬프트 템플릿 관리
  • 안전 필터링(출력 검증)
  • RAG/툴콜링 레이어(예: LangChain, LlamaIndex, 자체 에이전트 프레임워크)
    를 얹어서 써야 합니다.

ChatGPT Codex로 구현하기

바로 위 섹션을 코덱스를 통해서 구현해 보았습니다.
위 내용을 알려주고 설명을 해달라고 요구하니 다음과 같은 답변을 줍니다.

---Kanana‑2 Open Source 모델을 Python + Hugging Face로 “맛보기” 하려면 이렇게 진행하면 좋아요. 현재는 개념 설명 위주로 안내하고, 실제 실행 세팅은 다음 단계에서 환경에 맞게 맞춰가면 됩니다.

  진행 순서(요약)

  - 모델 접근 권한 확인: Hugging Face에서 kakaocorp/kanana-2-30b-a3b-thinking 페이지에 접근 가능한지 먼저
    확인
  - Python 환경 준비: python -m venv .venv 후 transformers, accelerate, torch 설치
  - GPU 환경 확인: CUDA 지원 여부, GPU VRAM 확인 (30B급은 수십 GB VRAM 필요)
  - 로딩 옵션 결정: device_map="auto" + torch_dtype=torch.bfloat16 등으로 메모리 최적화
  - 간단 질의 코드 실행: 샘플 프롬프트로 출력 확인

  핵심 체크포인트

  - VRAM이 충분하지 않으면: device_map="auto"로 CPU/GPU 분산, 혹은 더 작은 모델로 테스트
  - 속도/메모리 최적화: torch_dtype, low_cpu_mem_usage=True, max_new_tokens 조절
  - 추론 품질: temperature, top_p 등의 샘플링 파라미터 튜닝

------

현재 환경은 Apple M2 내장 GPU(Metal)이고, CUDA GPU는 없습니다. nvidia-smi도
  없어서 NVIDIA VRAM 기반 실행은 불가합니다. 이 경우 PyTorch의 MPS 백엔드로는 작은 모델만 실험 가능하고,
  30B급은 현실적으로 메모리/속도 한계가 큽니다.

  로컬 실행 옵션은 크게 두 가지예요:

  - 소형/중형 모델로 맛보기: M2에서 가능한 크기로 내려서 동작 확인
  - 원본 30B 모델은 원격 GPU: (예: 서버/클라우드/Colab)로 돌리기

-------현재 사용중인 노트북에서 14B 모델까지는 돌려보았는데 30B는 불가하다고 하여 코랩으로 한번 진행해보겠습니다.

코랩에서 실행하는 방법을 정리해 드릴게요. 30B 모델은 메모리 요구가 커서 A100 80GB 이상을 권장합니다. T4/
  L4는 매우 빡빡하거나 불가능할 수 있어요. 그래도 가능성을 높이려면 4-bit 양자화로 시도합니다.

  Colab 진행 순서

  1. Colab 런타임 → 하드웨어 가속기: GPU (가능하면 A100)
  2. Hugging Face 토큰 준비(모델 접근 권한 필요)
  3. 셀에서 라이브러리 설치
  4. 로그인 후 모델 로드/추론 실행

  Colab 셀 예시 (4-bit 양자화)

  !pip -q install transformers accelerate bitsandbytes

  from huggingface_hub import login
  login()  # 토큰 입력

  import torch
  from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig

  MODEL_ID = "kakaocorp/kanana-2-30b-a3b-thinking"

  bnb_config = BitsAndBytesConfig(
      load_in_4bit=True,
      bnb_4bit_quant_type="nf4",
      bnb_4bit_use_double_quant=True,
      bnb_4bit_compute_dtype=torch.bfloat16,
  )

  tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
  model = AutoModelForCausalLM.from_pretrained(
      MODEL_ID,
      device_map="auto",
      quantization_config=bnb_config,
  )

  def ask_kanana(prompt: str, max_tokens: int = 256) -> str:
      inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
      with torch.no_grad():
          output = model.generate(
              **inputs,
              max_new_tokens=max_tokens,
              do_sample=True,
              temperature=0.7,
          )
      return tokenizer.decode(output[0], skip_special_tokens=True)

  prompt = "당신은 에이전틱 AI 연구를 돕는 조수입니다. Kanana-2 오픈소스 모델의 특징을 한국어로 5줄 이내로
  요약해 주세요."
  print(ask_kanana(prompt))

  실패/메모리 부족 시 대안

  - 더 작은 모델로 테스트 (예: 7B/13B급)
  - max_new_tokens를 128 이하로 낮추기
  - torch_dtype=torch.float16로 바꾸기 (bfloat16 불가 GPU일 때)

위 내용 따라서 코랩에서 세팅을 하고 토큰을 준비해서 하려고 했으나 실제 토큰을 생성할 수 없는 상황임을 확인했고, 그래서 허깅페이스에서 직접 코랩으로 연결하는 작업을 해보았습니다.

(코랩 런타임 유형 선택)
(허깅페이스 kanana-2 코랩 사용 옵션)

위 그림에서처럼 Google Colab을 선택하면 다음과 같은 코드가 펼쳐진 코랩으로 연결이 됩니다. (물론 코랩 로그인이 되어 있어야겠지요.)

!pip install -U transformers

## Local Inference on GPU 
Model page: https://huggingface.co/kakaocorp/kanana-2-30b-a3b-thinking

⚠️ If the generated code snippets do not work, please open an issue on either the [model repo](https://huggingface.co/kakaocorp/kanana-2-30b-a3b-thinking)
			and/or on [huggingface.js](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/model-libraries-snippets.ts) 🙏

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("text-generation", model="kakaocorp/kanana-2-30b-a3b-thinking")
messages = [
    {"role": "user", "content": "Who are you?"},
]
pipe(messages)

# Load model directly
from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("kakaocorp/kanana-2-30b-a3b-thinking")
model = AutoModelForCausalLM.from_pretrained("kakaocorp/kanana-2-30b-a3b-thinking")
messages = [
    {"role": "user", "content": "Who are you?"},
]
inputs = tokenizer.apply_chat_template(
	messages,
	add_generation_prompt=True,
	tokenize=True,
	return_dict=True,
	return_tensors="pt",
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=40)
print(tokenizer.decode(outputs[0][inputs["input_ids"].shape[-1]:]))
이 오류는 'CUDA 메모리 부족' 오류입니다. GPU 메모리가 부족하여 모델을 로드할 수 없다는 뜻입니다. 모델의 메모리 사용량을 줄이기 위해 8비트 정밀도로 로드하도록 코드를 수정했습니다.

위와 같이 해도 기본 무료 자원용량으로는 30B 카나나를 돌릴 수가 없습니다.ㅜㅜ

Agentic AI 시나리오 예시 – “툴콜링 워크플로우”

툴콜링 워크플로우 이미지

예를 들어, “조직문화 면담 분석 에이전트”를 만든다고 가정해 볼게요. 툴콜링 워크플로우는 다음과 같아요.

  1. 사용자 프롬프트
    • “이번 분기 면담 기록을 요약하고, 주요 리스크 3가지를 뽑아서 Jira 이슈로 만들어줘.”
  2. Kanana-2 Instruct/Thinking에 System Prompt
    • “너는 조직문화 데이터 분석 에이전트다. 사용할 수 있는 도구는 다음 세 가지다…
      • search_interviews
      • summarize_text
      • create_jira_issue
        사용자 요청에 따라 어떤 도구를 어떤 순서로 부를지 JSON으로 반환해라.”
  3. 툴콜링 레이어
    • 모델이 내놓은 JSON을 파싱해서 실제 Python 함수 호출
  4. 최종 응답 구성
    • Jira 이슈 생성 결과 + 요약 결과를 다시 Kanana-2에게 넘겨 “사용자용 자연어 보고서”로 정리

이때 Kanana-2 오픈소스의 강점은

  • 한국어 면담 텍스트를 자연스럽게 이해하고
  • “도구를 어떤 순서로 호출할지”를 스스로 설계하는 데 최적화된 점입니다.

장점과 한계 – 솔직 리뷰

👍 Kanana-2 오픈소스의 장점

  • 한국어 중심 에이전트에 최적화
  • 도구 호출/지시 이행/추론(Thinking)에 신경 써서 튜닝된 모델
  • MLA + MoE 구조 덕분에, 같은 파라미터급 대비 추론 효율이 좋은 편
  • Hugging Face 공개 + 논문/기술문서까지 나와 있어 연구 용도로도 괜찮음

🤔 고려해야 할 한계

  • 30B급 모델은 로컬/소형 서버에선 부담이 크다
    • GPU 메모리, 비용, 인프라가 필요
  • Llama 3.x, Qwen 3.x처럼 글로벌 생태계가 큰 모델들에 비해
    • 튜토리얼, 예제, 커뮤니티 자료는 아직 적은 편
  • 라이선스가 Apache-2.0처럼 “매우 느슨한” 것은 아니라서
    • 기업 적용 전 법무/라이선스 검토는 필수

용어 정리 (초보자용)

  • Kanana-2 오픈소스
    카카오가 공개한 차세대 국산 LLM 시리즈. 에이전틱 AI와 도구 호출, 복잡한 지시 이행에 초점을 둔 모델 계열.
  • 에이전틱 AI (Agentic AI)
    단순히 답변만 하는 AI가 아니라,
    “상황 이해 → 필요한 작업(도구 호출/코드 실행 등) 선택 → 결과를 조합해 다시 응답”까지 스스로 하는 에이전트형 AI.
  • MLA (Multi-head Latent Attention)
    주어진 자원 안에서 효율을 높이기 위한 새로운 어텐션 구조. 기존 어텐션보다 계산량을 줄이면서도 성능을 유지하는 것을 목표로 합니다.
  • 专家混合体（MoE）
    여러 개의 “전문가 네트워크” 중 일부만 골라서 사용하는 구조.
    전체 파라미터는 크지만, 실제로는 일부만 활성화해서 연산량과 비용을 줄이는 트릭.
  • Thinking 모델
    내부적으로 “단계별 추론”을 강화한 LLM 계열을 흔히 부르는 이름.
    Kanana-2에서도 Thinking 버전이 따로 존재합니다.

类似文章