허깅페이스에서 모델을 로컬로 다운로드하는 방법

허깅페이스(Hugging Face)는 다양한 NLP·임베딩 모델을 제공합니다. 인터넷이 불안정하거나 보안·오프라인 환경 때문에 모델을 로컬에 내려받아 사용해야 할 때가 있습니다. 이 글에서는 sentence_transformers와 langchain으로 모델을 다운로드·저장하고, 로컬 경로에서 로드하는 방법을 단계별로 정리합니다.

💡 이런 분들께 추천합니다

• 오프라인·제한된 네트워크 환경에서 모델을 쓰려는 분
• 임베딩 모델을 로컬에 두고 LangChain 등과 연동하려는 분
• Hugging Face 모델 다운로드·저장 절차를 처음 해 보는 분

🧩 개념 설명 / 배경 지식

로컬 모델 사용
허깅페이스 허브에서 모델을 한 번 다운로드해 디스크에 저장해 두면, 이후에는 해당 경로만 지정해 로드할 수 있습니다. SentenceTransformer.save()로 디렉터리 형태로 저장하고, HuggingFaceEmbeddings(model_name="로컬경로")로 불러올 수 있습니다.

🔍 본론: 다운로드 및 로컬 로드

허깅페이스에서 모델을 로컬로 다운로드하고 사용하는 방법은 크게 두 단계로 나뉩니다. 첫 번째 단계는 모델을 다운로드하여 로컬에 저장하는 것이고, 두 번째 단계는 저장된 모델을 로드하여 사용하는 것입니다. 이를 위해 우리는 sentence_transformers와 langchain 라이브러리를 사용할 것입니다.

1. 모델 다운로드 및 저장

먼저, 허깅페이스에서 제공하는 jhgan/ko-sroberta-multitask 모델을 다운로드하여 로컬에 저장하는 방법을 살펴보겠습니다. 이를 위해 sentence_transformers 라이브러리를 사용할 것입니다.

from sentence_transformers import SentenceTransformer

# 모델 다운로드 및 로컬에 저장
model = SentenceTransformer("jhgan/ko-sroberta-multitask")
model.save("./local_ko_sroberta_multitask")

위 코드에서는 SentenceTransformer 클래스의 인스턴스를 생성하고, jhgan/ko-sroberta-multitask 모델을 다운로드합니다. 그런 다음, save 메서드를 사용하여 모델을 로컬 디렉토리인 ./local_ko_sroberta_multitask에 저장합니다.

2. 로컬 경로에서 임베딩된 모델 로드

이제 로컬에 저장된 모델을 로드하여 사용할 수 있습니다. 이를 위해 langchain 라이브러리의 HuggingFaceEmbeddings 클래스를 사용할 것입니다. 다음 예제에서는 데이터프레임을 사용하여 임베딩을 생성하고 이를 벡터스토어에 저장하는 방법을 자세히 설명합니다.

from langchain.embeddings import HuggingFaceEmbeddings
import pandas as pd

# 로컬에 저장된 모델 로드- 1번에서 저장된 파일위치 지정
embeddings = HuggingFaceEmbeddings(model_name="./local_ko_sroberta_multitask")

# 샘플 데이터프레임 생성
data = {
    'id': [1, 2, 3],
    'text': ["안녕하세요", "허깅페이스 모델 사용법", "로컬에서 모델 로드"]
}
df = pd.DataFrame(data)

# 데이터프레임에서 텍스트 임베딩 생성 및 벡터스토어 생성 함수
def create_vectorstore(df):
    # 각 텍스트에 대해 임베딩 생성
    df['embedding'] = df['text'].apply(lambda x: embeddings.embed([x])[0])
    
    # 벡터스토어 생성 (여기서는 간단히 딕셔너리로 표현)
    vectorstore = {row['id']: row['embedding'] for _, row in df.iterrows()}
    return vectorstore

# 벡터스토어 생성
vectorstore = create_vectorstore(df)

# 생성된 벡터스토어 출력
print(vectorstore)

위 코드에서는 다음과 같은 작업을 수행합니다:

1. HuggingFaceEmbeddings 클래스를 사용하여 로컬 경로에 저장된 모델을 로드합니다.
2. 샘플 데이터프레임을 생성합니다.
3. 데이터프레임의 각 텍스트에 대해 임베딩을 생성하고, 이를 벡터스토어에 저장합니다. 여기서 벡터스토어는 간단하게 딕셔너리로 표현됩니다.

이 예제를 통해 로컬에 저장된 모델을 사용하여 텍스트 임베딩을 생성하고, 이를 활용하는 방법을 이해할 수 있습니다.

⚠️ 주의사항

• 로컬에 저장할 경로에 쓰기 권한이 있어야 합니다. model.save() 시 동일한 경로를 HuggingFaceEmbeddings(model_name="...")에 넣을 때 절대 경로를 쓰면 이식성이 좋습니다.
• langchain의 HuggingFaceEmbeddings import 경로는 버전에 따라 langchain_community.embeddings 등으로 바뀔 수 있으니, 설치된 패키지 문서를 확인하세요.

✅ 실습 / 적용 예시

Step 1. 환경 준비
sentence_transformers, langchain(또는 langchain-community) 설치.
Step 2. 모델 다운로드·저장
SentenceTransformer("모델명").save("./로컬경로") 실행.
Step 3. 로컬 모델 로드
HuggingFaceEmbeddings(model_name="./로컬경로")로 임베딩 객체 생성 후, embed()로 벡터 생성 및 벡터스토어 구축.

🚧 트러블슈팅 / 자주 묻는 질문

Q. 로컬 경로를 넣었는데 모델을 찾을 수 없다고 나와요.
A. save()로 저장한 디렉터리 경로가 맞는지, config.json·pytorch_model.bin 등 파일이 있는지 확인하세요. 상대 경로 대신 절대 경로를 사용해 보세요.

Q. 다른 라이브러리에서 로컬 모델을 쓰려면?
A. transformers의 AutoModel.from_pretrained("./로컬경로") 등으로도 로드할 수 있습니다. 사용하는 라이브러리의 “load from local path” 문서를 참고하세요.

📝 마무리

• 다운로드: SentenceTransformer로 허브 모델을 내려받아 save()로 로컬에 저장할 수 있습니다.
• 로드: HuggingFaceEmbeddings(model_name="로컬경로")로 LangChain 파이프라인에 연동해 임베딩·벡터스토어를 만들 수 있습니다.
• 오프라인·보안 환경에서도 동일한 방식으로 로컬 모델을 활용해 보시면 됩니다.