ctransformers

ctransformers

ctransformers는 C/C++로 구현된 Transformer 모델을 GGML 라이브러리 위에서 실행할 수 있게 해 주는 Python 바인딩이에요. 핵심 추론 엔진은 C++ 기반이라 가볍고 빠르고, 필요에 따라 CUDA나 Metal을 활용해 GPU 가속도 지원해요. GGML이나 GGUF 포맷의 모델 파일을 그대로 불러와서 로컬에서 추론할 수 있고, 🤗 Transformers나 LangChain과도 손쉽게 연동할 수 있어요. 그래서 별도의 대형 딥러닝 프레임워크 없이도 간단한 API로 로컬 LLM 추론을 경험해 볼 수 있는 실용적인 도구랍니다.

출처: 문서

본문

핵심 개념

ctransformers는 추론을 C/C++ 엔진으로 처리하고, GGML(GPU 및 CPU에서 가볍게 동작하도록 설계된 머신러닝 텐서 라이브러리) 기반 모델 파일을 사용해요. 초기에는 GGML/GGUF 바이너리 포맷의 모델을 다뤘고, 최신 버전에서는 GGUF 모델도 지원해요. Python에서는 AutoModelForCausalLM이라는 통일된 인터페이스로 모든 모델을 같은 방식으로 다룰 수 있어요.

지원하는 주요 모델은 다음과 같아요.

모델 모델 타입 CUDA Metal
GPT-2 gpt2
GPT-J, GPT4All-J gptj
GPT-NeoX, StableLM gpt_neox
Falcon falcon ✅
LLaMA, LLaMA 2 llama ✅ ✅
MPT mpt ✅
StarCoder, StarChat gpt_bigcode ✅
Dolly V2 dolly-v2
Replit replit

설치

설치는 pip로 간단하게 할 수 있어요.

pip install ctransformers

사용 예시

모든 모델에 공통으로 쓰이는 통일된 인터페이스를 제공해요.

from ctransformers import AutoModelForCausalLM

llm = AutoModelForCausalLM.from_pretrained("/path/to/ggml-model.bin", model_type="gpt2")

print(llm("AI is going to"))

출력을 스트리밍으로 받고 싶다면 stream=True를 설정해요.

for text in llm("AI is going to", stream=True):
    print(text, end="", flush=True)

Hugging Face Hub에서 모델을 바로 불러올 수도 있어요.

llm = AutoModelForCausalLM.from_pretrained("marella/gpt-2-ggml")

모델 저장소에 여러 모델 파일(.bin 또는 .gguf 파일)이 있다면 model_file로 원하는 파일을 지정해요.

llm = AutoModelForCausalLM.from_pretrained("marella/gpt-2-ggml", model_file="ggml-model.bin")

🤗 Transformers와 함께 쓰기

참고: 실험적인 기능이라 추후 변경될 수 있어요.

🤗 Transformers 모델과 토크나이저로 만들려면 다음과 같이 해요.

from ctransformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("marella/gpt-2-ggml", hf=True)
tokenizer = AutoTokenizer.from_pretrained(model)

그러면 🤗 Transformers의 텍스트 생성 파이프라인을 그대로 사용할 수 있어요.

from transformers import pipeline

pipe = pipeline("text-generation", model=model, tokenizer=tokenizer)
print(pipe("AI is going to", max_new_tokens=256))

생성 파라미터도 🤗 Transformers의 것과 동일하게 넘길 수 있어요.

pipe("AI is going to", max_new_tokens=256, do_sample=True, temperature=0.8, repetition_penalty=1.1)

토크나이저는 원본 모델 저장소에서 따로 불러올 수도 있어요.

from ctransformers import AutoModelForCausalLM
from transformers import AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("marella/gpt-2-ggml", hf=True)  # Load model from GGML model repo.
tokenizer = AutoTokenizer.from_pretrained("gpt2")  # Load tokenizer from original model repo.

LangChain과 함께 쓰기

ctransformers는 LangChain에 통합되어 있어요. 자세한 내용은 LangChain 문서에서 확인할 수 있어요.

GPU 사용하기

모델 레이어 중 일부를 GPU에서 실행하려면 gpu_layers 파라미터를 지정해요.

llm = AutoModelForCausalLM.from_pretrained("TheBloke/Llama-2-7B-GGML", gpu_layers=50)

CUDA 지원은 다음 명령으로 설치해요.

pip install ctransformers[cuda]

ROCm 지원을 켜려면 다음과 같이 설치해요.

CT_HIPBLAS=1 pip install ctransformers --no-binary ctransformers

Metal 지원을 켜려면 다음과 같이 설치해요.

CT_METAL=1 pip install ctransformers --no-binary ctransformers

GPTQ

참고: 실험적인 기능이며 ExLlama를 사용해 LLaMA 모델만 지원해요.

추가 의존성을 설치해요.

pip install ctransformers[gptq]

GPTQ 모델을 불러올 때는 다음과 같이 해요.

llm = AutoModelForCausalLM.from_pretrained("TheBloke/Llama-2-7B-GPTQ")

모델 이름이나 경로에 gptq라는 단어가 없다면 model_type="gptq"를 지정해 줘요.

GPTQ 모델도 LangChain과 함께 쓸 수 있지만, 저수준 API는 완전히 지원되지 않아요.

주요 설정 파라미터

파라미터 타입 설명 기본값
top_k int 샘플링에 사용할 top-k 값. 40
top_p float 샘플링에 사용할 top-p 값. 0.95
temperature float 샘플링에 사용할 temperature 값. 0.8
repetition_penalty float 샘플링에 사용할 반복 페널티. 1.1
last_n_tokens int 반복 페널티에 사용할 마지막 토큰 수. 64
seed int 토큰 샘플링에 사용할 시드 값. -1
max_new_tokens int 생성할 새 토큰의 최대 개수. 256
stop List[str] 만나면 생성을 중단할 시퀀스 목록. None
stream bool 생성된 텍스트를 스트리밍할지 여부. False
reset bool 텍스트 생성 전에 모델 상태를 초기화할지 여부. True
batch_size int 단일 프롬프트에서 토큰을 평가할 배치 크기. 8
threads int 토큰 평가에 사용할 스레드 수. -1
context_length int 사용할 최대 컨텍스트 길이. -1
gpu_layers int GPU에서 실행할 레이어 수. 0

참고: 현재 context_length 파라미터는 LLaMA, MPT, Falcon 모델만 지원해요.

라이선스

ctransformers는 MIT 라이선스를 사용해요.

더 알아보기 (Learn more)