ChatOllama 통합

ChatOllama 통합 (ChatOllama integration · LangChain Python)

LangChain Python에서 ChatOllama 채팅 모델과 통합하는 방법을 다뤄요.

Ollama는 gpt-oss 같은 오픈소스 대규모 언어 모델(LLM)을 로컬에서 직접 실행하게 해 주는 도구예요. Ollama는 모델 가중치, 설정, 데이터를 Modelfile이라는 단일 패키지로 묶어 줘요. GPU 사용을 포함한 설치·설정 과정을 최적화해 주죠.

지원되는 모델과 변형의 전체 목록은 Ollama 모델 라이브러리를 참고하세요.

출처: 공식문서

🔗 API 레퍼런스: 모든 기능과 설정 옵션의 상세 문서는 ChatOllama API 레퍼런스를 보세요.

개요

통합 정보

클래스 패키지 Serializable JS 지원
ChatOllama langchain-ollama ❌ ✅

모델 기능

도구 호출 구조화된 출력 이미지 입력 오디오 입력 비디오 입력 토큰 단위 스트리밍 Native async 토큰 사용량 Logprobs
✅ ✅ ✅ ❌ ❌ ✅ ✅ ❌ ✅

설정 (Setup)

먼저 이 안내를 따라 로컬 Ollama 인스턴스를 설치하고 실행하세요.

  • 다운로드하고 지원 플랫폼(WSL을 포함한 Windows Subsystem for Linux, macOS, Linux)에 Ollama를 설치하세요
    • macOS 사용자는 Homebrew로 brew install ollama 후 brew services start ollama로 시작할 수 있어요
  • ollama pull <name-of-model>로 원하는 LLM 모델을 내려받으세요
    • 사용 가능한 모델 목록은 모델 라이브러리에서 볼 수 있어요
    • 예: ollama pull gpt-oss:20b
  • 이렇게 하면 모델의 기본 태그(default tagged) 버전이 내려와요. 보통 기본은 최신이면서 가장 작은 파라미터 크기의 모델을 가리켜요

Mac에서는 모델이 ~/.ollama/models에 내려와요.

Linux(또는 WSL)에서는 모델이 /usr/share/ollama/.ollama/models에 저장돼요.

  • 관심 있는 모델의 정확한 버전을 지정하려면 ollama pull gpt-oss:20b처럼 쓰면 돼요 (이 경우 Vicuna 모델의 다양한 태그를 볼 수 있어요)
  • 내려받은 모델 전체를 보려면 ollama list를 쓰세요
  • 명령줄에서 모델과 바로 대화하려면 ollama run <name-of-model>을 쓰세요
  • 더 많은 명령은 Ollama 문서를 보세요. 터미널에서 ollama help를 실행해 사용 가능한 명령을 볼 수도 있어요

모델 호출에 대한 자동 추적(tracing)을 켜려면 LangSmith API 키를 설정하세요.

os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")

설치 (Installation)

LangChain Ollama 통합은 langchain-ollama 패키지에 있어요.

pip install -qU langchain-ollama

인스턴스 생성 (Instantiation)

이제 모델 객체를 만들고 채팅 완성(chat completions)을 생성할 수 있어요.

from langchain_ollama import ChatOllama

llm = ChatOllama(
    model="llama3.1",
    temperature=0,
    # other params...
)

호출 (Invocation)

messages = [
    (
        "system",
        "You are a helpful assistant that translates English to French. Translate the user sentence.",
    ),
    ("human", "I love programming."),
]
ai_msg = llm.invoke(messages)
ai_msg

AIMessage(content='The translation of "I love programming" in French is:\n\n"J\'adore la programmation."', additional_kwargs={}, response_metadata={'model': 'llama3.1', 'created_at': '2025-06-25T18:43:00.483666Z', 'done': True, 'done_reason': 'stop', 'total_duration': 619971208, 'load_duration': 27793125, 'prompt_eval_count': 35, 'prompt_eval_duration': 36354583, 'eval_count': 22, 'eval_duration': 555182667, 'model_name': 'llama3.1'}, id='run--348bb5ef-9dd9-4271-bc7e-a9ddb54c28c1-0', usage_metadata={'input_tokens': 35, 'output_tokens': 22, 'total_tokens': 57})

print(ai_msg.content)

The translation of "I love programming" in French is:

"J'adore le programmation."

도구 호출 (Tool calling)

Ollama 도구 호출은 OpenAI 호환 웹 서버 스펙을 사용해요. LangChain 도구 문서에 설명된 기본 BaseChatModel.bind_tools() 메서드로 사용할 수 있어요.

도구 호출을 지원하는 Ollama 모델을 선택해야 해요.

도구 사용에 맞게 파인튜닝된 LLM(예: gpt-oss)과 함께 도구 호출을 쓸 수 있어요.

ollama pull gpt-oss:20b

커스텀 도구를 만드는 자세한 내용은 도구 속성 커스터마이즈에서 확인할 수 있어요. 아래에서는 일반 파이썬 함수에 @tool 데코레이터를 써서 도구를 만드는 방법을 보여 드릴게요.

from typing import List

from langchain.messages import AIMessage
from langchain.tools import tool
from langchain_ollama import ChatOllama


@tool
def validate_user(user_id: int, addresses: List[str]) -> bool:
    """Validate user using historical addresses.

    Args:
        user_id (int): the user ID.
        addresses (List[str]): Previous addresses as a list of strings.
    """
    return True


llm = ChatOllama(
    model="gpt-oss:20b",
    validate_model_on_init=True,
    temperature=0,
).bind_tools([validate_user])

result = llm.invoke(
    "Could you validate user 123? They previously lived at "
    "123 Fake St in Boston MA and 234 Pretend Boulevard in "
    "Houston TX."
)

if isinstance(result, AIMessage) and result.tool_calls:
    print(result.tool_calls)

[{'name': 'validate_user', 'args': {'addresses': ['123 Fake St, Boston, MA', '234 Pretend Boulevard, Houston, TX'], 'user_id': '123'}, 'id': 'aef33a32-a34b-4b37-b054-e0d85584772f', 'type': 'tool_call'}]

멀티모달 (Multi-modal)

Ollama는 gemma3 같은 멀티모달 LLM을 제한적으로 지원해요.

멀티모달을 지원받으려면 Ollama를 최신 버전으로 업데이트해야 해요.

pip install pillow

import base64
from io import BytesIO

from IPython.display import HTML, display
from PIL import Image


def convert_to_base64(pil_image):
    """
    Convert PIL images to Base64 encoded strings

    :param pil_image: PIL image
    :return: Re-sized Base64 string
    """

    buffered = BytesIO()
    pil_image.save(buffered, format="JPEG")  # You can change the format if needed
    img_str = base64.b64encode(buffered.getvalue()).decode("utf-8")
    return img_str


def plt_img_base64(img_base64):
    """
    Display base64 encoded string as image

    :param img_base64:  Base64 string
    """
    # Create an HTML img tag with the base64 string as the source
    image_html = f'<img src="data:image/jpeg;base64,{img_base64}" />'
    # Display the image by rendering the HTML
    display(HTML(image_html))


file_path = "../../../static/img/ollama_example_img.jpg"
pil_image = Image.open(file_path)

image_b64 = convert_to_base64(pil_image)
plt_img_base64(image_b64)

<img src="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJ..." />

from langchain.messages import HumanMessage
from langchain_ollama import ChatOllama

llm = ChatOllama(model="bakllava", temperature=0)


def prompt_func(data):
    text = data["text"]
    image = data["image"]

    image_part = {
        "type": "image_url",
        "image_url": f"data:image/jpeg;base64,{image}",
    }

    content_parts = []

    text_part = {"type": "text", "text": text}

    content_parts.append(image_part)
    content_parts.append(text_part)

    return [HumanMessage(content=content_parts)]


from langchain_core.output_parsers import StrOutputParser

chain = prompt_func | llm | StrOutputParser()

query_chain = chain.invoke(
    {"text": "What is the Dollar-based gross retention rate?", "image": image_b64}
)

print(query_chain)

90%

로그 확률 (Log probabilities)

ChatOllama는 logprobs와 top_logprobs 파라미터로 토큰 단위 로그 확률을 지원해요. 로그 확률은 각 생성 단계에서 각 토큰이 얼마나 유력했는지를 나타내요.

기본 사용법

from langchain_ollama import ChatOllama

llm = ChatOllama(model="llama3.1", logprobs=True)

response = llm.invoke("What color is the sky?")
logprobs = response.response_metadata["logprobs"]
for entry in logprobs[:5]:
    print(f"Token: {entry['token']!r:>15}  logprob: {entry['logprob']:.4f}")

Token:           'The'  logprob: -0.1094
Token:       ' answer'  logprob: -1.7309
Token:             ','  logprob: -1.5854
Token:           ' of'  logprob: -0.4066
Token:       ' course'  logprob: -0.0000

토큰별 Top-K 대안

top_logprobs를 쓰면 각 위치에서 가장 유력한 대안 토큰들을 반환해 줘요.

llm = ChatOllama(model="llama3.1", logprobs=True, top_logprobs=3)

response = llm.invoke("The capital of France is")
logprobs = response.response_metadata["logprobs"]
for entry in logprobs[:3]:
    print(f"Chosen: {entry['token']!r}")
    if entry.get("top_logprobs"):
        for alt in entry["top_logprobs"]:
            print(f"    {alt['token']!r:>12}  logprob: {alt['logprob']:.4f}")

Chosen: 'Paris'
         'Paris'  logprob: -0.5567
           'The'  logprob: -0.9152
            '**'  logprob: -4.0410
Chosen: '.'
             '.'  logprob: -0.3831
    '<|eot_id|>'  logprob: -1.5511
             '!'  logprob: -2.3379

추론 모델과 커스텀 메시지 역할

IBM의 Granite 3.2 같은 일부 모델은 사고(thinking) 과정을 활성화하는 커스텀 메시지 역할을 지원해요.

Granite 3.2의 thinking 기능에 접근하려면 "control" 역할에 "thinking" 내용을 담은 메시지를 넘겨주세요. "control"은 비표준 메시지 역할이라 ChatMessage 객체로 구현할 수 있어요.

from langchain.messages import HumanMessage
from langchain_core.messages import ChatMessage
from langchain_ollama import ChatOllama

llm = ChatOllama(model="granite3.2:8b")

messages = [
    ChatMessage(role="control", content="thinking"),
    HumanMessage("What is 3^3?"),
]

response = llm.invoke(messages)
print(response.content)

Here is my thought process:
The user is asking for the value of 3 raised to the power of 3, which is a basic exponentiation operation.

Here is my response:

3^3 (read as "3 to the power of 3") equals 27.

This calculation is performed by multiplying 3 by itself three times: 3*3*3 = 27.

모델이 최종 응답과 함께 사고 과정도 노출한다는 점을 참고하세요.

API 레퍼런스

ChatOllama의 모든 기능과 설정의 상세 문서는 API 레퍼런스를 보세요.