Ollama API คู่มือแก้ปัญหา

ทำความเข้าใจโครงสร้างจุดสิ้นสุด API ของ ollama

The ollama endpoint ยึดตามรูปแบบ RESTful อย่างเคร่งครัด โดยจำลองโครงสร้าง API ของ OpenAI คุณสามารถใช้งานโดยการส่งคำขอ POST ไปยัง /v1/chat/completions และสอบถามโมเดลที่มีอยู่ผ่าน GET /v1/models. มาตรฐานนี้ช่วยให้คุณสลับโมเดลพื้นฐานได้โดยไม่ต้องเขียนโค้ดไคลเอนต์ใหม่

นักพัฒนาจำนวนมากคิดว่าเอนด์พอยต์รองรับ embeddings หรือการสร้างภาพโดยค่าเริ่มต้น มันไม่รองรับ บริการโฮสต์ของเราตัวอย่างเช่น ให้เฉพาะการเติมข้อความด้วยโมเดล uncensored เดียวเสมอตรวจสอบ GET /v1/models รูปแบบคำตอบ เพื่อดูความสามารถที่เปิดเผยอย่างชัดเจน หากคุณเห็นรายการโมเดล ให้ตรวจสอบ ID ของพวกมันก่อนส่งคำขอ

เมื่อใช้อินสแตนซ์ในเครื่อง จุดปลายมักจะทำงานบน http://localhost:11434. สำหรับผู้ให้บริการคลาวด์ คุณจะใช้ URL พื้นฐานแบบกำหนดเอง ตรวจสอบให้แน่ใจว่าไคลเอนต์ HTTP ของคุณจัดการหัวเรื่องได้ถูกต้อง โดยเฉพาะ Content-Type: application/json. header ที่หายไปมักทำให้เกิดความล้มเหลวแบบเงียบที่ดูเหมือนข้อผิดพลาดของโมเดล

องค์ประกอบโครงสร้างสำคัญ:

• model: ตัวระบุสตริงสำหรับ LLM เฉพาะ
• messages: อาร์เรย์ของวัตถุเนื้อหาที่กำหนดบทบาท
• stream: บูลีนแฟล็กที่เปิดใช้งาน Server-Sent Events (SSE).

ทำไมการเรียกใช้ API ollama ของคุณอาจล้มเหลว

API calls มักล้มเหลวเนื่องจาก base URLs ที่ไม่ถูกต้อง key ที่หมดอายุ หรือ payload JSON ที่ผิดรูปแบบ ข้อผิดพลาดที่พบบ่อยที่สุดคือ 401 Unauthorized ซึ่งหมายความว่า API key ของคุณหายไปหรือไม่ถูกต้อง อีกปัญหาที่พบบ่อยคือ 404 Not Found ซึ่งบ่งชี้ว่า endpoint ไม่รองรับ path หรือ model ID ที่ร้องขอ

ตรวจสอบร่างกายคำขอของคุณอย่างระมัดระวัง หากคุณส่งพารามิเตอร์ที่จุดสิ้นสุดไม่รองรับ เช่น modalities สำหรับโมเดลที่รองรับเฉพาะข้อความ เซิร์ฟเวอร์อาจปฏิเสธคำขอ บริการของเราตัวอย่างเช่นไม่รองรับการป้อนข้อมูลภาพ การส่งข้อมูลภาพจะเกิดข้อผิดพลาดทันที

การหมดเวลาของเครือข่ายยังทำให้เกิดความล้มเหลวด้วย หากอินสแตนซ์ Ollama ในเครื่องของคุณไม่ได้ใช้งาน มันอาจโหลดโมเดลออกจาก VRAM คำขอแรกหลังจากการเริ่มต้นเย็นอาจใช้เวลาหลายวินาที ตั้งค่าเวลาหมดเวลาที่เพียงพอในไคลเอนต์ HTTP ของคุณเพื่อหลีกเลี่ยงการตัดการเชื่อมต่อล่วงหน้า

รหัสข้อผิดพลาดทั่วไป:

• 400: Bad Request (JSON ที่ไม่ถูกต้องหรือพารามิเตอร์ไม่ถูกต้อง)
• 401: Unauthorized (คีย์ API ไม่ถูกต้องหรือหายไป)
• 429: Too Many Requests (เกินขีดจำกัดอัตราการใช้งาน)
• 500: Internal Server Error (ล้มเหลวในการโหลดโมเดล)

กำลังกำหนดค่าโมเดล ollama แบบไร้เซ็นเซอร์อย่างถูกต้อง

โมเดล Uncensored มักต้องการพารามิเตอร์เฉพาะเพื่อให้ทำงานตามที่คาดหวัง ความแตกต่างหลักอยู่ที่ system prompt คุณต้องสั่งให้โมเดลข้ามการปฏิเสธมาตรฐานอย่างชัดเจน หากไม่มี system prompt ที่แข็งแรง โมเดลอาจกลับสู่พฤติกรรมความปลอดภัยเริ่มต้น

จุดจบ API ของเราใช้ id โมเดล uncensored. คุณส่งคำขอไปยัง ID นี้ และเซิร์ฟเวอร์จะจัดการการเลือกโมเดลพื้นฐาน สิ่งนี้ลดความซับซ้อนของการจัดการเวอร์ชันโมเดล คุณไม่จำเป็นต้องรู้ว่าสถาปัตยกรรมพื้นฐานเป็นแบบ Llama หรือ Mistral

ปรับ temperature พารามิเตอร์นี้เพื่อควบคุมความคิดสร้างสรรค์ ค่า 0.7 เป็นจุดเริ่มต้นที่ดีสำหรับการตอบสนองที่สมดุล ค่าที่สูงขึ้นเพิ่มความสุ่ม ซึ่งมีประโยชน์สำหรับการเขียนเชิงสร้างสรรค์แต่อาจลดความถูกต้องของข้อเท็จจริง ค่าที่ต่ำกว่าทำให้เอาต์พุตมีความแน่นอนมากขึ้น

เคล็ดลับการกำหนดค่า:

• ใช้ top_p เคียงข้าง temperature เพื่อควบคุมที่ดีขึ้น
• ตั้งค่า stop ลำดับเพื่อป้องกันลูปไม่สิ้นสุด
• ควรใส่ system message for role definition.

การจัดการสตรีมและขีดจำกัดโทเค็น

การตอบสนองแบบสตรีมส่งข้อมูลเป็นชิ้นส่วนผ่านเหตุการณ์ที่ส่งจากเซิร์ฟเวอร์ (SSE) แต่ละชิ้นส่วนประกอบด้วยผลลัพธ์บางส่วน คุณต้องประกอบชิ้นส่วนเหล่านี้เพื่อรับการตอบสนองทั้งหมด บริการของเรารวมถึงสถิติการใช้งานโทเค็นในชิ้นส่วนสุดท้าย ซึ่งช่วยให้คุณติดตามต้นทุนแบบเรียลไทม์ได้

ขีดจำกัดของโทเค็นมีความสำคัญสำหรับการสนทนาที่ยาวนาน จุดสิ้นสุดของเรารองรับหน้าต่างบริบทขนาด 100,000 โทเค็น ซึ่งรวมทั้งพรอมต์และการตอบกลับ อย่างไรก็ตาม ขนาดเอาต์พุตสูงสุดต่อคำขอคือ 16,000 โทเค็น หากคุณไม่ได้ตั้งค่า max_tokens, ค่าเริ่มต้นคือ 2,048 tokens สิ่งนี้อาจทำให้คำตอบยาวๆ ถูกตัด unexpectedly

เมื่อสตรีม ให้จัดการการหยุดชะงักของเครือข่ายอย่างสุภาพ หากการเชื่อมต่อหลุดลง คุณสามารถดำเนินการต่อจากชิ้นส่วนสุดท้ายที่ได้รับหากเซิร์ฟเวอร์รองรับ มิฉะนั้น คุณอาจต้องลองส่งคำขอใหม่ทั้งหมด โปรดติดตาม usage field in the final chunk to avoid billing surprises.

แนวปฏิบัติที่ดีที่สุดสำหรับการสตรีม:

• แยกวิเคราะห์เหตุการณ์ SSE ได้อย่างถูกต้อง โดยละเว้นบรรทัดว่าง
• สะสม chunk ในหน่วยความจำหรือ buffer
• ตรวจสอบ usage object ใน chunk สุดท้ายสำหรับจำนวน token

ข้อผิดพลาดด้านการเรียกเก็บเงินและคณิตศาสตร์โทเค็น

ข้อผิดพลาดด้านการเรียกเก็บเงินมักเกิดจากความเข้าใจผิดเกี่ยวกับการนับโทเค็น โทเค็นจะถูกเรียกเก็บสำหรับทั้งอินพุต (prompt) และเอาต์พุต (completion) ราคาของเราคือ $0.15 ต่อ 1M โทเค็นอินพุต และ $0.50 ต่อ 1M โทเค็นเอาต์พุต ข้อผิดพลาดและการปฏิเสธไม่มีการเรียกเก็บเงิน ซึ่งช่วยลดต้นทุนในการดีบัก

ตัวแบ่งโทเค็นไม่จับคู่ 1:1 กับอักขระเสมอไป คำเดียวสามารถเป็นหลายโทเค็นได้ หากคุณประมาณการต้นทุนโดยนับจำนวนอักขระ คุณอาจประเมินต้นทุนต่ำเกินไป ใช้ไลบรารีตัวแบ่งโทเค็นที่เชื่อถือได้ในไคลเอนต์ของคุณเพื่อรับจำนวนที่แม่นยำก่อนส่งคำขอ

เครดิตไม่หมดอายุ หากคุณเติมเงินด้วยคริปโต ยอดเงินจะคงอยู่จนกว่าคุณจะใช้งาน สิ่งนี้มีประโยชน์สำหรับโครงการระยะยาว อย่างไรก็ตาม โปรดทราบว่าแต่ละ request จะใช้ tokens จากยอดเงินของคุณ หากยอดเงินของคุณต่ำ request ถัดไปอาจล้มเหลว

เคล็ดลับการเรียกเก็บเงิน:

• ติดตามการใช้งาน token ในทุก response
• ตั้งค่าการแจ้งเตือนสำหรับเกณฑ์ยอดคงเหลือต่ำ
• ใช้ max_tokens เพื่อจำกัดต้นทุนที่อาจเกิดขึ้น

ปัญหาความปลอดภัยและการสแกนพอร์ต

จุดปลาย API Ollama ท้องถิ่นมักจะถูกเปิดเผยต่อเครือข่ายโดยค่าเริ่มต้น สิ่งนี้ทำให้มันเสี่ยงต่อการสแกนพอร์ตที่มองหาพลังการคำนวณฟรี หากคุณเปิดพอร์ต 11434 โดยไม่มีการตรวจสอบสิทธิ์ ใครก็ตามสามารถใช้ทรัพยากร GPU ของคุณได้ สิ่งนี้อาจนำไปสู่บิลค่าไฟฟ้าที่สูงและประสิทธิภาพที่ช้าลง

ปกป้อง endpoint ของคุณโดยการเปลี่ยนพอร์ตเริ่มต้นหรือใช้ reverse proxy พร้อมการตรวจสอบสิทธิ์ บริการโฮสต์ของเราจัดการความปลอดภัยให้คุณ ดังนั้นคุณไม่ต้องกังวลเกี่ยวกับการเปิดเผยพอร์ต คุณเพียงต้องรักษาความลับของคีย์ API ของคุณ

สำหรับการตั้งค่าในเครื่อง ให้ใช้ไฟร์วอลล์เพื่อจำกัดการเข้าถึงเฉพาะที่อยู่ IP ที่เชื่อถือได้ คุณยังสามารถเปิดใช้งานการตรวจสอบสิทธิ์ด้วยโทเค็นในไฟล์กำหนดค่าของ Ollama ได้ สิ่งนี้ป้องกันไม่ให้ผู้ใช้ที่ไม่ได้รับอนุญาตส่งคำขอ

ขั้นตอนความปลอดภัย:

• เปลี่ยนพอร์ตเริ่มต้นหากเปิดใช้งานสู่อินเทอร์เน็ต
• ใช้พร็อกซีกลับพร้อม HTTPS และ auth
• ตรวจสอบการจราจรเครือข่ายของคุณเพื่อหากิจกรรมผิดปกติ

การใช้งาน API ollama แบบท้องถิ่น เทียบกับคลาวด์

การใช้งานท้องถิ่นให้คุณควบคุมความเป็นส่วนตัวของข้อมูลและการเลือกโมเดลได้อย่างเต็มที่ คุณสามารถรันโมเดลหลายตัวพร้อมกันและสลับระหว่างพวกเขาได้ทันที อย่างไรก็ตาม คุณรับผิดชอบการบำรุงรักษาฮาร์ดแวร์ การอัปเดต และความปลอดภัย การใช้งานบนคลาวด์โอนภาระเหล่านี้ไปยังผู้ให้บริการ

บริการคลาวด์ของเราเสนอโมเดล uncensored ที่ปรับแต่งสำหรับการสร้างเนื้อหาแบบไม่มีข้อจำกัด คุณเข้าถึงได้ทันทีโดยไม่ต้องดาวน์โหลดไฟล์โมเดลขนาดใหญ่ ข้อเสียคือข้อมูลของคุณจะผ่านเซิร์ฟเวอร์ของเรา สำหรับข้อมูลที่มีความละเอียดอ่อน การใช้งานแบบโลคัลอาจเป็นทางเลือกที่ดีกว่า

บริการบนคลาวด์มักมีความหน่วงเนื่องจากเวลาในการเดินทางของเครือข่าย อินสแตนซ์ในท้องถิ่นมีความหน่วงเกือบเป็นศูนย์หาก GPU เร็วพอ อย่างไรก็ตาม อินสแตนซ์ในท้องถิ่นต้องการ VRAM จำนวนมาก หาก GPU ของคุณหมดหน่วยความจำ โมเดลอาจสลับไปใช้ CPU ซึ่งทำให้การตอบสนองช้าลงอย่างมาก

การเปรียบเทียบ:

• ท้องถิ่น: ความเป็นส่วนตัว การควบคุม และความต้องการฮาร์ดแวร์
• คลาวด์: ความสะดวก ความสามารถในการขยายขนาด และการถ่ายโอนข้อมูล

ข้อผิดพลาดทั่วไปฝั่งไคลเอนต์

นักพัฒนาหลายคนมักลืมจัดการขีดจำกัดอัตราการใช้งาน บริการของเราอนุญาตให้ใช้ 300 คำขอต่อนาทีต่อคีย์ หากคุณเกินขีดจำกัดนี้ คุณจะได้รับข้อผิดพลาด 429 ควรใช้การหน่วงเวลาแบบเอกซ์โพเนนเชียลในไคลเอนต์ของคุณเพื่อจัดการข้อผิดพลาดเหล่านี้อย่างราบรื่น

ความผิดพลาดอีกประการหนึ่งคือการไม่ตั้งค่า stream parameter correctly. If you expect streaming but do not set stream: true, คุณจะรอการตอบกลับทั้งหมดก่อนที่จะได้รับข้อมูลใดๆ สิ่งนี้สามารถทำให้แอปของคุณรู้สึกช้า

ข้อผิดพลาดของโหมด JSON ก็พบได้บ่อยเช่นกัน หากคุณตั้งค่า response_format: {type: "json_object"}, โมเดลต้องส่งคืน JSON ที่ถูกต้อง หากไม่เป็นเช่นนั้น parser ของคุณจะล้มเหลว เพิ่มการจัดการข้อผิดพลาดเพื่อจับและลองใหม่เมื่อเกิดข้อผิดพลาดในการ parse JSON

รายการตรวจสอบ:

• เพิ่มการจัดการขีดจำกัดอัตรา (rate limit)
• ตั้งค่า stream: true สำหรับการอัปเดตแบบเรียลไทม์
• ตรวจสอบผลลัพธ์ JSON เมื่อใช้โหมด JSON