पायथन में Ollama API और एक होस्टेड विकल्प

संक्षिप्त संस्करण

यदि आप ollama api python खोजते हैं, तो आप आमतौर पर इनमें से एक चीज़ चाहते हैं: अपने मशीन पर चल रहे मॉडल को कॉल करें, उससे टोकन स्ट्रीम करें, या उसी स्क्रिप्ट को कहीं और काम करने दें। Ollama आपको तीनों देता है। यह एक स्थानीय सर्वर चलाता है, डिफ़ॉल्ट रूप से http://localhost:11434 पर, और आप ollama Python पैकेज, सादे HTTP, या इसके /v1 पथ पर इंगित किसी भी OpenAI क्लाइंट के साथ इससे बात करते हैं।

यहाँ शर्त यह है कि मॉडल को आपके हार्डवेयर पर चलना चाहिए। एक लैपटॉप जिसमें उचित GPU नहीं है, बड़े मॉडल के साथ धीमा होगा, और एक सर्वर जिसमें ऐसा नहीं है, उसके लिए यह अच्छा विकल्प नहीं है। उस मामले के लिए, एक होस्टेड OpenAI-संगत API आसान मार्ग है, और क्योंकि अनुरोध प्रारूप समान है, स्विच करने में आपको कॉन्फ़िगरेशन की केवल तीन पंक्तियाँ खर्च होती हैं। दोनों मार्गों को नीचे कवर किया गया है, जिसमें कोड है जिसे आप पेस्ट कर सकते हैं।

स्थानीय मॉडल को ollama पैकेज के साथ कॉल करना

Ollama इंस्टॉल करें, एक मॉडल खींचें, और सुनिश्चित करें कि सर्वर चल रहा है। फिर Python क्लाइंट इंस्टॉल करें:

Copypip install ollama
ollama pull llama3.2

एक बुनियादी चैट कॉल इस प्रकार दिखती है। मॉडल का नाम वही है जो आपने खींचा है; llama3.2 केवल एक उदाहरण है।

Copyimport ollama

response = ollama.chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Explain DNS in two sentences."}],
)
print(response["message"]["content"])

स्ट्रीमिंग

stream=True पास करें और आपको एक इटरेटर मिलता है चंक का, एक ही रिप्लाई के बजाय। प्रत्येक चंक message.content में जवाब का एक हिस्सा ले जाता है।

Copyimport ollama

stream = ollama.chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Write a haiku about servers."}],
    stream=True,
)
for chunk in stream:
    print(chunk["message"]["content"], end="", flush=True)
print()

क्लाइंट को दूसरी मशीन पर इंगित करना

यदि Ollama किसी अलग होस्ट पर चल रहा है, तो एक स्पष्ट पता देकर क्लाइंट बनाएँ, उदाहरण के लिए ollama.Client(host="http://192.168.1.20:11434")। डिफ़ॉल्ट रूप से सर्वर केवल स्थानीय मशीन पर ही सुनता है, इसलिए रिमोट एक्सेस के लिए सर्वर साइड पर जानबूझकर सेटिंग करनी होगी। इसे प्रॉक्सी और प्रमाणीकरण के बिना सार्वजनिक इंटरनेट पर न खोलें, क्योंकि नेटिव API का अपना कोई कुंजी चेक नहीं है।

requests के साथ सादा HTTP

आपको पैकेज की बिल्कुल आवश्यकता नहीं है। नेटिव चैट एंडपॉइंट POST /api/chat है। वहां स्ट्रीमिंग डिफ़ॉल्ट है, और स्ट्रीम न्यूलाइन-डिलिमिटेड JSON है, न कि SSE। यदि आप एक अकेला ऑब्जेक्ट वापस चाहते हैं तो "stream": false सेट करें।

Copyimport requests

r = requests.post(
    "http://localhost:11434/api/chat",
    json={
        "model": "llama3.2",
        "messages": [{"role": "user", "content": "Name three HTTP status codes."}],
        "stream": False,
    },
    timeout=120,
)
r.raise_for_status()
print(r.json()["message"]["content"])

एक प्रचुर टाइमआउट सेट करें। खींचने के बाद पहला अनुरोध मॉडल को मेमोरी में लोड करने के लिए है, और यह बाद के अनुरोधों की तुलना में बहुत अधिक समय ले सकता है।

स्ट्रीम को हाथ से पढ़ना केवल कुछ और लाइनों का मामला है। requests.post(..., stream=True) कॉल करें, r.iter_lines() पर लूप चलाएं, खाली लाइनों को छोड़ें, और प्रत्येक पर json.loads चलाएं। प्रत्येक ऑब्जेक्ट रिप्लाई का एक छोटा सा हिस्सा रखता है, और आखिरी वाले में "done": true होता है। यह एक मिनिमल कंटेनर में उपयोगी है जहां आप एक और पैकेज इंस्टॉल नहीं करना चाहते, और यह स्पष्ट करता है कि लाइब्रेरी आपके लिए क्या करती है। होस्टेड API अलग तरह से स्ट्रीम करता है, SSE लाइनों के रूप में जो data: से शुरू होती हैं, जो एक और कारण है कि OpenAI SDK को पोर्टेबल कोड में स्ट्रीम को आपके लिए पार्स करने दें।

Ollama के साथ OpenAI SDK का उपयोग करना

Ollama /v1 के तहत एक OpenAI-शैली एंडपॉइंट भी एक्सपोज़ करता है। इसका मतलब है कि आधिकारिक openai पैकेज काम करता है, और अधिकांश सॉफ़्टवेयर भी काम करता है जो आपको एक कस्टम बेस URL सेट करने देता है। कुंजी SDK द्वारा आवश्यक है लेकिन एक स्थानीय Ollama द्वारा अनदेखा की जाती है, इसलिए कोई भी स्ट्रिंग काम करेगी।

Copyfrom openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Give me a one-line summary of TCP."}],
)
print(resp.choices[0].message.content)

यह सबसे उपयोगी रूप है, क्योंकि यह आपके कोड को सर्वर से अलग करता है। वही फ़ंक्शन आज एक स्थानीय मॉडल से बात कर सकता है और कल कुछ और से, जो अगला अनुभाग है।

वही कोड होस्टेड API के लिए

यहाँ होस्टेड विकल्प एक OpenAI-संगत API है जिसमें एक ही मॉडल uncensored है, जो एक स्वतंत्र प्रदाता द्वारा चलाया जाता है और कानूनी वयस्क उपयोग के लिए सामग्री अस्वीकृति के बिना उत्तर देने के लिए ट्यून्ड है। यह केवल टेक्स्ट के लिए है। बेस यूआरएल है https://api.ollamaapi.cc/v1, और आप API कुंजी पृष्ठ से प्राप्त बीयरर कुंजी से प्रमाणीकरण करते हैं।

यहाँ एक संस्करण है जो अपने लक्ष्य को एनवायरनमेंट वेरिएबल्स से पढ़ता है, होस्टेड मानों को डिफ़ॉल्ट के रूप में रखते हुए। अपने स्थानीय सर्वर पर वापस जाने के लिए, दो वेरिएबल्स एक्सपोर्ट करें और कुछ भी अन्य नहीं बदलें।

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("LLM_BASE_URL", "https://api.ollamaapi.cc/v1"),
    api_key=os.getenv("LLM_API_KEY", "YOUR_API_KEY"),
)
MODEL = os.getenv("LLM_MODEL", "uncensored")

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "List four uses of a message queue."},
    ],
    temperature=0.7,
)
print(resp.choices[0].message.content)

स्थानीय रन के लिए, LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama और LLM_MODEL=llama3.2 सेट करें। quickstart में curl और Node में वही सेटअप है।

होस्टेड साइड पर स्ट्रीमिंग, JSON मोड और टूल्स

होस्टेड एंडपॉइंट SSE पर स्ट्रीमिंग, JSON मोड, टूल कॉलिंग, और सामान्य सैंपलिंग पैरामीटर (temperature, top_p, stop, seed और पेनल्टी) का समर्थन करता है। SDK के साथ स्ट्रीमिंग वही लूप है जिसे आप किसी भी OpenAI-शैली सर्वर के लिए लिखते:

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell a two-paragraph story about a lighthouse."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

संरचित आउटपुट के लिए, response_format={"type": "json_object"} सेट करें और प्रॉम्प्ट में बताएं कि आपको JSON चाहिए। किसी भी मामले में इसे try ब्लॉक के अंदर ही पार्स करें; मॉडल अभी भी कुछ ऐसा लौटा सकता है जिसकी आपने उम्मीद नहीं की थी।

लोकल उपयोग से एक अंतर कोड में मायने रखता है: लिमिट्स। एक फुल कुंजी 8 समानांतर अनुरोध और प्रति मिनट 300 अनुरोध की अनुमति देती है, और एक स्ट्रीम किए गए अनुरोध में उसका स्लॉट स्ट्रीम खत्म होने तक बना रहता है। यदि आप थ्रेड्स के साथ फैन आउट करते हैं, तो पॉल को 8 पर कैप करें और HTTP 429 पर Retry-After हेडर उपस्थित होने पर रेट्राई करें।

बातचीत को जारी रखना

न तो स्थानीय चैट एंडपॉइंट और न ही होस्टेड चैट एंडपॉइंट कॉल के बीच कुछ भी याद रखता है। सर्वर केवल आपके द्वारा भेजे गए संदेश देखता है, इसलिए एक चैटबॉट एक लिस्ट है जिसे आप एपेंड करते हैं और फिर से भेजते हैं। यह पैटर्न दोनों टारगेट के लिए समान है, जो OpenAI-शैली क्लाइंट को अपनी डिफ़ॉल्ट बनाए रखने का एक और कारण है।

Copyhistory = [{"role": "system", "content": "You are a helpful assistant."}]

def ask(text):
    history.append({"role": "user", "content": text})
    resp = client.chat.completions.create(model=MODEL, messages=history)
    answer = resp.choices[0].message.content
    history.append({"role": "assistant", "content": answer})
    return answer

print(ask("Pick a name for a hiking app."))
print(ask("Give me a tagline for it."))

दो व्यावहारिक नोट्स। पहला, लोकल मॉडल्स में एक कॉन्टेक्स्ट लेंथ होती है जिसे आप सेट करते हैं और जिसे मेमोरी को हैल्ड करना होता है; यदि इतिहास उससे आगे बढ़ जाता है, तो पुराने टर्न्स को काट दिया जाता है या सेटिंग्स के आधार पर कॉल फेल हो जाती है। होस्टेड मॉडल 100,000-टोकन विंडो स्वीकार करता है जिसमें कम्पलीशन भी शामिल है, जो ज्यादातर चैट्स की ज़रूरत से कहीं अधिक है, लेकिन लंबे इतिहास के लिए हर टर्न पर इनपुट टोकन की लागत आती है। दूसरा, एक बार जब इतिहास लंबा हो जाए, तो सबसे पुराने टर्न्स को एक छोटे संदेश में सारांशित करें, उन सभी को फिर से भेजने के बजाय। यह किसी भी बैकएंड पर लेटेंसी और लागत को स्थिर रखता है।

विनम्रतापूर्वक पुनः प्रयास करना

होस्टेड API पर एक अस्थायी ओवरलोड HTTP 429 लौटाता है एक Retry-After: 5 हेडर के साथ। एक छोटा रैपर इसे हैंडल करता है:

Copyimport time
from openai import RateLimitError

def chat_with_retry(messages, tries=4):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model=MODEL, messages=messages)
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    raise RuntimeError("still rate limited")

स्थानीय Ollama आप पर रेट लिमिट नहीं लगाता, लेकिन मॉडल व्यस्त होने पर अनुरोधों को कतार में रखता है, इसलिए वही रैपर वहां भी नुकसान नहीं करता।

स्थानीय या होस्टेड: निर्णय कैसे लें

सामान्य तौर पर कोई भी विकल्प बेहतर नहीं है। नीचे दिए गए बिंदुओं को एक चेकलिस्ट के रूप में उपयोग करें।

• स्थानीय Ollama चुनें यदि आपको ऑफलाइन काम करने की आवश्यकता है, यदि डेटा कभी भी मशीन से बाहर नहीं जाना चाहिए, यदि आपके पास पहले से एक सक्षम GPU है, या यदि आप कई अलग-अलग ओपन मॉडल्स को जल्दी आज़माना चाहते हैं।
• होस्टेड API चुनें यदि आपके पास GPU नहीं है, यदि आप छोटे VPS या CI पर चलाते हैं, यदि कई लोग या सेवाएँ एक ही बैकएंड साझा करती हैं, या यदि आप मेमोरी का आकार खुद तय किए बिना लंबी कॉन्टेक्स्ट विंडो चाहते हैं। होस्टेड मॉडल प्रॉम्प्ट और कम्पलीशन मिलाकर 100,000 टोकन तक स्वीकार करता है।
• विकास के दौरान दोनों को मिलाएं: स्थानीय रूप से इटरेट करें, फिर एन्वायरनमेंट वेरिएबल्स के माध्यम से प्रोडक्शन को होस्टेड URL पर पॉइंट करें।

होस्टेड उपयोग प्रति टोकन बिल किया जाता है, $0.15 प्रति 1M इनपुट टोकन और $0.50 प्रति 1M आउटपुट टोकन की दर से, प्रीपेड क्रेडिट से। मूल्य निर्धारण पृष्ठ पर टॉप-अप राशियाँ सूचीबद्ध हैं, और नए अकाउंट्स एक क्लिक में $0.50 का ट्रायल ले सकते हैं, कार्ड की आवश्यकता नहीं है। प्रॉम्प्ट्स को ट्रेनिंग के लिए उपयोग नहीं किया जाता है।

त्रुटियाँ जो आप सामना करेंगे

लक्षण	संभावित कारण	समाधान
पोर्ट 11434 पर कनेक्शन रिफ्यूज	Ollama सर्वर चालू नहीं है	ऐप चालू करें या ollama serve चलाएं
मॉडल नहीं मिला	मॉडल कभी खींचा नहीं गया था, या नाम में टाइपो है	ollama list चलाएं, फिर ollama pull उस नाम को चलाएं जिसका आप उपयोग करते हैं
पहली कॉल टाइमआउट हो जाती है	मॉडल अभी भी लोड हो रहा है	टाइमआउट बढ़ाएं, या एक वॉर्म-अप अनुरोध भेजें
होस्टेड API पर प्रमाणीकरण त्रुटि	मिसिंग या गलत Bearer कुंजी	LLM_API_KEY और बेस URL की जांच करें
कोड concurrency के साथ HTTP 429	प्रगति में 8 से अधिक अनुरोध (ट्रायल कुंजी पर 2)	वर्कर काउंट कम करें
कोड rate_limited के साथ HTTP 429	प्रति मिनट अनुरोधों की सीमा से अधिक	बैकऑफ़ करें और पुनः प्रयास करें

होस्टेड साइड पर विफल या अस्वीकृत अनुरोधों के लिए चार्ज नहीं किया जाता है, इसलिए रीट्राई लॉजिक विफल प्रयासों के लिए आपको खर्च नहीं कराता है।

अधिक गाइड

• Ollama API मूल्य निर्धारण: स्थानीय लागत बनाम प्रति टोकन भुगतान
• Ollama API बनाम OpenRouter: कौन सा आपको फिट बैठता है
• Mistral API कुंजी गाइड