Python용 Ollama API, 그 다음 호스팅 엔드포인트

Python 클라이언트 설정

먼저 Ollama 자체를 설치하고 실행한 다음 터미널에서 모델을 가져옵니다: ollama pull llama3. 서버는 http://localhost:11434에서 수신 대기합니다. 그런 다음 가상 환경에서 Python 패키지를 설치합니다:

Copypython -m venv .venv
source .venv/bin/activate
pip install ollama openai

ollama 패키지는 /api 아래의 Ollama 네이티브 라우트와 통신합니다. openai 패키지는 이 튜토리얼의 두 번째 부분, 즉 대상이 호스팅 엔드포인트인 경우에 사용됩니다. 코딩 전에 시각적 도구를 선호한다면 GUI를 사용한 Ollama 사용에 대한 노트를 참조하십시오.

터미널에서 ollama list를 실행하여 설치를 확인합니다. 모델이 거기에 나타나면 Python이 이를 찾습니다. 나중에 연결 오류가 발생하면 서버가 실행 중이지 않을 가능성이 높습니다.

첫 번째 채팅 호출

이것은 ollama api python의 기본 사항을 하나의 스니펫으로 보여줍니다: 시스템 메시지, 사용자 메시지 및 두 가지 옵션입니다.

Copyimport ollama

resp = ollama.chat(
    model="llama3",
    messages=[
        {"role": "system", "content": "Answer in one short paragraph."},
        {"role": "user", "content": "What is a context window?"},
    ],
    options={"temperature": 0.4, "num_ctx": 8192},
)
print(resp["message"]["content"])

응답은 사전과 같은 객체이며, 텍스트는 message.content에 저장됩니다. options에서 생성 매개변수를 설정할 수 있습니다. temperature은 무작위성을 조절하고, num_ctx은 해당 호출의 컨텍스트 길이를 설정합니다. Ollama는 컨텍스트 크기를 명시적으로 높이지 않는 한 비교적 작은 컨텍스트를 기본값으로 사용하므로, 긴 문서를 붙여넣고도 시작 부분을 무시하는 답변을 받으면 놀랄 수 있습니다.

다중 턴 채팅의 경우 메시지 목록을 유지하고 각 응답을 직접 추가하세요. Ollama는 대부분의 채팅 API와 마찬가지로 호출 간에 상태를 유지하지 않습니다.

스트리밍 응답

스트리밍을 사용하지 않으면 전체 답변이 올 때까지 기다려야 합니다. stream=True를 사용하면 함수가 제네레이터를 반환하며, 도착하는 대로 조각을 출력할 수 있습니다:

Copyimport ollama

for part in ollama.chat(
    model="llama3",
    messages=[{"role": "user", "content": "Explain recursion with a cooking analogy."}],
    stream=True,
):
    print(part["message"]["content"], end="", flush=True)

각 조각에는 작은 message.content가 포함됩니다. 마지막 조각에는 done이 true로 설정되어 있으며, 처리 시간과 토큰 사용량이 포함됩니다. 웹 앱의 경우 서버 전송 이벤트(SSE) 또는 웹소켓을 통해 이러한 조각을 브라우저로 전달하세요.

실제로 발생하는 오류

두 가지 실패가 대부분의 초보자 문제를 포괄합니다.

Copyimport ollama

try:
    ollama.chat(model="llama3", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as exc:
    if exc.status_code == 404:
        print("Model missing. Run: ollama pull llama3")
    else:
        raise
except ConnectionError:
    print("Cannot reach Ollama. Is the server running on port 11434?")

ResponseError에서 404가 발생하면 모델 이름이 pull 명령으로 가져온 모델과 일치하지 않습니다. 이름에는 태그가 포함되므로 llama3와 llama3:70b은 서로 다른 모델입니다. 연결 오류가 발생하면 서버가 실행 중이지 않거나, localhost가 호스트가 아닌 컨테이너를 가리키는 컨테이너 내부에 있을 수 있습니다. 이 경우 올바른 호스트를 가진 클라이언트를 전달하세요: ollama.Client(host="http://host.docker.internal:11434").

더 많은 패턴은 일반적인 Ollama API 실수에 수집되어 있습니다.

동일한 프로그램, 호스팅 엔드포인트

로컬 모델은 메모리와 속도에 의해 제한됩니다. 스크립트가 서버에서 실행해야 하거나 많은 병렬 작업을 처리해야 하거나 더 큰 창을 사용해야 할 때 호스팅 엔드포인트가 더 쉽습니다. 열쇠는 OpenAI SDK를 대상으로 프로그램을 작성하고 base URL, 키 및 모델을 구성으로 처리하는 것입니다:

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.ollamansfw.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt, history=None):
    messages = (history or []) + [{"role": "user", "content": prompt}]
    out = ""
    for chunk in client.chat.completions.create(model=MODEL, messages=messages, stream=True):
        if chunk.choices and chunk.choices[0].delta.content:
            piece = chunk.choices[0].delta.content
            out += piece
            print(piece, end="", flush=True)
    return out

ask("Explain recursion with a cooking analogy.")

로컬 Ollama의 경우 LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (해당 필드에는 비어 있지 않은 문자열이면 무엇이든 허용됨) 및 LLM_MODEL=llama3을 설정하세요. 호스팅 API의 경우 위의 기본값, 실제 API 키 및 모델 uncensored을 사용하세요. 코드에서 다른 변경 사항은 없습니다.

API 키 페이지에서 키를 얻으세요. 새 계정은 결제 없이 한 번의 클릭으로 7일 동안 유효한 $0.50 무료 체험 크레딧을 받을 수 있습니다. 이 모델은 독립적인 제공업체의 오픈 웨이트 모델 중 하나로, 합법적인 성인 사용 목적에 대해 콘텐츠 거부 없이 답변하도록 조정되었습니다. 텍스트 전용이며 주요 연구소의 공식 API가 아닙니다.

여러 프롬프트 병렬 실행

한 대의 머신에 있는 로컬 모델은 일반적으로 한 번에 하나의 요청만 처리하므로 루프는 순차적으로 실행됩니다. 호스팅 엔드포인트는 동시성을 지원하여 배치 작업을 훨씬 빠르게 처리합니다. 작업자 수를 API 키의 제한 내에 유지하세요: 전체 키의 경우 동시 요청 8개, 체험 키의 경우 2개입니다.

Copyfrom concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

def summarize(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarize in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

docs = ["first text", "second text", "third text"]
with ThreadPoolExecutor(max_workers=6) as pool:
    results = list(pool.map(summarize, docs))
print(results)

6개의 워커는 8이라는 제한 아래에 여유 공간을 확보합니다. 워커가 429 오류를 받으면 OpenAI SDK는 기본적으로 몇 번 다시 시도하지만, 긴 실행의 경우 자체 백오프를 추가하세요. 또한 스트리밍 요청은 스트림이 끝날 때까지 슬롯을 유지하므로, 동일한 체험 키에서 긴 스트리밍 채팅과 큰 배치 작업을 혼합하지 마세요.

계획할 차이점

• 로컬 전용 옵션 없음. num_ctx 및 keep_alive는 호스팅 측에서 의미가 없습니다. 창은 프롬프트와 완성 합계로 100,000 토큰입니다.
• 속도 제한. 전체 키는 동시 요청 8개와 분당 300개의 요청을 허용하며, 체험 키는 각각 2개와 60개를 허용합니다. 이를 초과하면 rate_limited 또는 concurrency 오류와 함께 HTTP 429 응답을 받습니다. 잠시 대기 후 다시 시도하세요. 일시적인 과부하 시 응답 헤더에 Retry-After: 5가 포함됩니다.
• 비용. 입력은 토큰 100만 개당 $0.15이며 출력은 토큰 100만 개당 $0.50입니다. 600 입력 토큰과 400 출력 토큰으로 2,000개의 프롬프트를 보내는 스크립트는 2,000 x (600 x $0.15 + 400 x $0.50) / 1M = 2,000 x $0.00029 = $0.58을 지출합니다.
• 청구. 선불 크레딧, $20부터 $500까지, 암호화폐(TRC20의 USDT 또는 Base의 USDC)로 지불합니다. 실패하거나 거부된 요청은 요금이 부과되지 않습니다.

엔드포인트를 나란히 비교하려면 API 요금 안내 또는 문서를 읽으세요.

더 많은 가이드

• Ollama API vs OpenAI API: 엔드포인트 및 코드
• GUI와 함께 Ollama 사용 방법 (및 호스팅 폴백)