راهنمای رفع اشکال API Ollama

درک ساختار نقطه پایانی API اولاما (Ollama)

The ollama endpoint الگوی RESTful دقیقی را دنبال می‌کند که ساختار API OpenAI را بازتاب می‌دهد. شما با ارسال درخواست‌های POST به /v1/chat/completions و مدل‌های موجود را از طریق GET /v1/models. این استانداردسازی به شما امکان می‌دهد مدل‌های زیرین را بدون بازنویسی کد کلاینت خود جابجا کنید.

بسیاری از توسعه‌دهندگان فرض می‌کنند که نقطه پایانی به طور پیش‌فرض از جاسازی‌ها (embeddings) یا تولید تصویر پشتیبانی می‌کند. این‌طور نیست. سرویس میزبانی ما، برای مثال، فقط تکمیل‌های متنی را با یک مدل بدون سانسور ارائه می‌دهد. همیشه بررسی کنید GET /v1/models پاسخ را بررسی کنید تا دقیقاً ببینید کدام قابلیت‌ها در دسترس هستند. اگر لیستی از مدل‌ها را مشاهده کردید، شناسه‌های آن‌ها را قبل از ارسال درخواست‌ها بررسی کنید.

هنگام استفاده از یک نمونه محلی، نقطه پایان معمولاً روی http://localhost:11434. برای ارائه‌دهندگان ابری، از یک URL پایه سفارشی استفاده خواهید کرد. اطمینان حاصل کنید که کلاینت HTTP شما هدرها را به درستی مدیریت می‌کند، به ویژه Content-Type: application/json. یک هدر گم‌شده اغلب باعث شکست‌های خاموشی می‌شود که شبیه خطاهای مدل به نظر می‌رسند.

عناصر ساختاری کلید:

• model: شناسه رشته‌ای برای مدل LLM خاص.
• messages: تصادفی‌سازی را تنظیم می‌کند.
• stream: یک پرچم بولی که رویدادهای ارسالی سرور (SSE) را فعال می‌کند.

چرا ممکن است فراخوانی‌های API ollama شما شکست بخورد

معمولاً تماس‌های API به دلیل URLهای پایه نادرست، کلیدهای منقضی شده یا پیکربندی‌های JSON نامعتبر شکست می‌خورند. رایج‌ترین خطا، پاسخ 401 Unauthorized است که به این معنی است که کلید API شما وجود ندارد یا نامعتبر است. مشکل رایج دیگر 404 Not Found است که نشان می‌دهد پایانه مسیر یا شناسه مدل درخواستی را پشتیبانی نمی‌کند.

بدنه درخواست خود را با دقت بررسی کنید. اگر پارامتری را ارسال کنید که نقطه پایانی پشتیبانی نمی‌کند، مانند modalities برای یک مدل فقط متنی، سرور ممکن است درخواست را رد کند. سرویس ما، برای مثال، از ورودی تصویر پشتیبانی نمی‌کند. ارسال آن منجر به خطای فوری می‌شود.

زمان‌های انتظار شبکه نیز باعث شکست می‌شوند. اگر نمونه Ollama محلی شما غیرفعال باشد، ممکن است مدل را از VRAM بارگذاری کند. اولین درخواست پس از شروع سرد می‌تواند چندین ثانیه طول بکشد. یک زمان‌های انتظار سخاوتمندانه در کلاینت HTTP خود تنظیم کنید تا از قطع‌های زودهنگام جلوگیری شود.

کدهای خطای رایج:

• 400: Bad Request (JSON نادرست یا پارامترهای نامعتبر).
• 401: غیرمجاز (کلید API نامعتبر یا موجود نیست).
• 429: تعداد درخواست‌ها بیش از حد است (محدودیت نرخ تجاوز شده).
• 500: Internal Server Error (شکست در بارگذاری مدل).

پیکربندی صحیح مدل‌های ollama بدون سانسور

مدل‌های بدون سانسور اغلب به پارامترهای خاصی نیاز دارند تا همان‌طور که انتظار می‌رود رفتار کنند. تفاوت اصلی در system prompt. باید صراحتاً به مدل دستور دهید تا از ردّهای استاندارد بگذرد. بدون یک system prompt قوی، مدل ممکن است به رفتارهای ایمنی پیش‌فرض بازگردد.

نقطه پایانی ما از شناسه مدل uncensored. درخواست‌ها را به این شناسه ارسال می‌کنید و سرور انتخاب مدل زیرین را مدیریت می‌کند. این پیچیدگی مدیریت نسخه‌های مدل را انتزاع می‌کند. نیازی نیست بدانید آیا معماری زیرین مبتنی بر Llama است یا Mistral.

تنظیم temperature پارامتر را برای کنترل خلاقیت تنظیم کنید. مقدار ۰.۷ نقطه شروع خوبی برای پاسخ‌های متعادل است. مقادیر بالاتر تصادفی بودن را افزایش می‌دهند که برای نویسندگی خلاق مفید است اما ممکن است دقت واقعی را کاهش دهد. مقادیر پایین‌تر خروجی را قطعی‌تر می‌کند.

نکات پیکربندی:

• استفاده top_p در کنار temperature برای کنترل بهتر.
• تنظیم stop توالی‌ها برای جلوگیری از حلقه‌های بی‌نهایت.
• همیشه یک system پیام برای تعریف نقش.

مدیریت جریان‌سازی و محدودیت توکن

پاسخ‌های استریم‌شده داده‌ها را در قالب قطعات از طریق رویدادهای Server-Sent Events (SSE) برمی‌گردانند. هر قطعه حاوی یک تکمیل جزئی است. شما باید این قطعات را کنار هم بگذارید تا پاسخ کامل را دریافت کنید. سرویس ما آمار مصرف توکن را در قطعه‌ی نهایی شامل می‌شود و به شما امکان می‌دهد هزینه‌ها را به‌طور بلادرست ردیابی کنید.

محدودیت‌های توکن برای مکالمات طولانی حیاتی هستند. نقطه پایانی ما از پنجره زمینه ۱۰۰,۰۰۰ توکن پشتیبانی می‌کند که ترکیبی از پرامپت و تکمیل است. با این حال، حداکثر خروجی در هر درخواست ۱۶,۰۰۰ توکن است. اگر max_tokens, پیش‌فرض ۲,۰۴۸ توکن است. این می‌تواند پاسخ‌های طولانی را به طور غیرمنتظره کوتاه کند.

هنگام Streaming، وقفه‌های شبکه را به صورت Graceful مدیریت کنید. اگر اتصال قطع شد، می‌توانید از آخرین Chunk دریافت شده ادامه دهید اگر سرور از آن پشتیبانی کند. در غیر این صورت، ممکن است نیاز باشد کل درخواست را مجدداً ارسال کنید. همیشه usage field in the final chunk to avoid billing surprises.

بهترین شیوه‌های پخش زنده:

• رویدادهای SSE را به درستی تجزیه کنید و خطوط خالی را نادیده بگیرید.
• تکه‌ها را در حافظه یا یک بافر انباشته کنید.
• بررسی کنید usage object در آخرین قطعه برای شمارش توکن‌ها.

خطاهای صورتحساب و حسابرسی توکن

خطاهای صورتحساب اغلب ناشی از عدم درک نحوه شمارش توکن‌ها است. توکن‌ها هم برای ورودی (پرامپت) و هم برای خروجی (تکمیل) شارژ می‌شوند. قیمت‌گذاری ما $0.15 به ازای هر 1M توکن ورودی و $0.50 به ازای هر 1M توکن خروجی است. خطاها و رد شدن‌ها رایگان هستند که هزینه‌های اشکال‌زدایی را کاهش می‌دهد.

توکنایزرها همیشه با کاراکترها رابطه ۱:۱ برقرار نمی‌کنند. یک کلمه می‌تواند چند توکن باشد. اگر هزینه‌ها را بر اساس تعداد کاراکتر تخمین بزنید، ممکن است قبض را کمتر از حد واقعی ببینید. از یک کتابخانه توکنایزر قابل اعتماد در کلاینت خود برای دریافت شمارش‌های دقیق قبل از ارسال درخواست‌ها استفاده کنید.

اعتبار منقضی نمی‌شود. اگر با ارز دیجیتال شارژ می‌کنید، موجودی تا زمانی که از آن استفاده کنید باقی می‌ماند. این برای پروژه‌های بلندمدت مفید است. با این حال، توجه داشته باشید که هر درخواست توکن‌هایی از موجودی شما مصرف می‌کند. اگر موجودی شما کم باشد، درخواست‌های بعدی ممکن است شکست بخورند.

نکات صورتحساب:

• مصرف توکن را در هر پاسخ ردیابی کنید.
• هشدارهایی برای آستانه‌های موجودی کم تنظیم کنید.
• استفاده max_tokens برای محدود کردن هزینه‌های بالقوه.

مشکلات امنیت و اسکن پورت

نقاط پایانی Ollama محلی اغلب به‌طور پیش‌فرض در معرض شبکه قرار می‌گیرند. این آن‌ها را در برابر اسکنرهای پورت که به دنبال محاسبات رایگان هستند، آسیب‌پذیر می‌کند. اگر پورت 11434 را بدون احراز هویت قرار دهید، هر کسی می‌تواند از منابع GPU شما استفاده کند. این می‌تواند منجر به هزینه‌های بالای برق و کاهش عملکرد شود.

نقطه پایانی خود را با تغییر پورت پیش‌فرض یا استفاده از یک پروکسی معکوس با احراز هویت امن کنید. سرویس میزبانی‌شده ما امنیت را برای شما مدیریت می‌کند، بنابراین نیازی به نگرانی در مورد قرار گرفتن پورت در معرض ندارید. شما فقط باید کلید API خود را خصوصی نگه دارید.

برای تنظیمات محلی، از یک فایروال برای محدود کردن دسترسی به آدرس‌های IP مورد اعتماد استفاده کنید. همچنین می‌توانید احراز هویت مبتنی بر توکن را در فایل پیکربندی Ollama فعال کنید. این کار از درخواست‌های کاربران غیرمجاز جلوگیری می‌کند.

مراحل امنیتی:

• پورت پیش‌فرض را در صورت قرار دادن در اینترنت تغییر دهید.
• از یک پروکسی معکوس با HTTPS و احراز هویت استفاده کنید.
• ترافیک شبکه خود را برای فعالیت‌های غیرعادی پایش کنید.

استفاده از API ollama محلی در مقابل ابری

استفاده محلی به شما کنترل کامل بر حریم خصوصی داده و انتخاب مدل را می‌دهد. می‌توانید چندین مدل را همزمان اجرا کنید و به سرعت بین آن‌ها جابجا شوید. با این حال، شما مسئول نگهداری سخت‌افزار، به‌روزرسانی‌ها و امنیت هستید. استفاده ابری این مسئولیت‌ها را به ارائه‌دهنده منتقل می‌کند.

خدمات ابری ما یک مدل بدون سانسور ارائه می‌دهد که برای تولید محتوای بدون محدودیت بهینه‌سازی شده است. شما دسترسی فوری بدون دانلود فایل‌های بزرگ مدل دارید. نقطه ضعف این است که داده‌های شما از سرورهای ما عبور می‌کند. برای داده‌های حساس، استفاده محلی ممکن است ترجیح داده شود.

خدمات ابری اغلب دارای تأخیر بالاتر به دلیل پیمایش‌های شبکه هستند. نمونه‌های محلی اگر GPU به اندازه کافی سریع باشد، دارای تأخیر نزدیک به صفر هستند. با این حال، نمونه‌های محلی به VRAM قابل‌توجهی نیاز دارند. اگر GPU شما حافظه کم آورد، مدل ممکن است به CPU منتقل شود که پاسخ‌ها را به‌طور چشمگیری کند می‌کند.

مقایسه:

• محلی: حریم خصوصی، کنترل و وابستگی به سخت‌افزار.
• ابری: راحتی، مقیاس‌پذیری، انتقال داده.

اشتباهات رایج سمت کلاینت

توسعه‌دهندگان اغلب فراموش می‌کنند که محدودیت‌های نرخ را مدیریت کنند. سرویس ما اجازه ۳۰۰ درخواست در دقیقه به ازای هر کلید را می‌دهد. اگر این حد را تجاوز کنید، خطای ۴۲۹ دریافت خواهید کرد. در کلاینت خود از بازگشت نمایی (exponential backoff) برای مدیریت این خطاها به صورت ایمن استفاده کنید.

یکی از اشتباهات دیگر، نادیده گرفتن stream پارامتر به‌درستی. اگر انتظار استریم دارید اما stream: true, تا دریافت تمام پاسخ قبل از دریافت هر داده منتظر می‌مانید. این می‌تواند باعث کند به نظر رسیدن برنامه شما شود.

خطاهای حالت JSON نیز رایج هستند. اگر Set response_format: {type: "json_object"}, مدل باید JSON معتبر برگرداند. اگر نه، پارسر شما شکست می‌خورد. مدیریت خطا را اضافه کنید تا خطاهای پارسینگ JSON را بگیرد و دوباره تلاش کند.

چک‌لیست:

• مدیریت محدودیت نرخ (rate limit) را پیاده‌سازی کنید.
• تنظیم stream: true بر برای به‌روزرسانی‌های در زمان واقعی.
• خروجی JSON را هنگام استفاده از حالت JSON اعتبارسنجی کنید.