การผสานรวมพาร์ทเนอร์และห้องสมุด

คู่มือนี้อธิบายกลยุทธ์ด้านสถาปัตยกรรมสำหรับการสร้างไลบรารี แพลตฟอร์ม และเกตเวย์บน Gemini API โดยจะอธิบายรายละเอียดการแลกเปลี่ยนทางเทคนิค ระหว่างการใช้ GenAI SDK อย่างเป็นทางการ, Direct API (REST/gRPC) และ เลเยอร์ความเข้ากันได้ของ OpenAI

ใช้คู่มือนี้หากคุณกำลังสร้างเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์คนอื่นๆ เช่น เฟรมเวิร์กโอเพนซอร์ส เกตเวย์ขององค์กร หรือผู้รวบรวม SaaS และต้องการ เพิ่มประสิทธิภาพเพื่อความสะอาดของทรัพยากร Dependency ขนาดของแพ็กเกจ หรือความเท่าเทียมของฟีเจอร์

การผสานรวมกับพาร์ทเนอร์คืออะไร

พาร์ทเนอร์คือทุกคนที่สร้างการผสานรวมระหว่าง Gemini API กับนักพัฒนาซอฟต์แวร์ที่เป็นผู้ใช้ปลายทาง เราจัดหมวดหมู่พาร์ทเนอร์เป็น 4 กลุ่ม การระบุว่าคุณตรงกับข้อใดมากที่สุดจะช่วยให้คุณเลือกเส้นทางการผสานรวมที่เหมาะสมได้

กรอบระบบนิเวศ

• คุณคือใคร: ผู้ดูแลเฟรมเวิร์กโอเพนซอร์ส (เช่น LangChain, LlamaIndex, Spring AI) หรือไคลเอ็นต์เฉพาะภาษา
• เป้าหมาย: ความเข้ากันได้ในวงกว้าง คุณต้องการให้ไลบรารีทำงานในสภาพแวดล้อมใดก็ได้ที่ผู้ใช้เลือกโดยไม่บังคับให้เกิดความขัดแย้ง

รันไทม์และแพลตฟอร์ม Edge

• คุณคือใคร: แพลตฟอร์ม SaaS, เกตเวย์ AI หรือผู้ให้บริการโครงสร้างพื้นฐานระบบคลาวด์ (เช่น Vercel, Cloudflare, Zapier) ซึ่งมีการรันโค้ดในสภาพแวดล้อมที่จำกัด
• เป้าหมายของคุณ: ประสิทธิภาพ คุณต้องมีเวลาในการตอบสนองต่ำ ขนาดแพ็กเกจเล็กที่สุด และ การเริ่มแอปแบบ Cold Start ที่รวดเร็ว

ผู้รวบรวมข้อมูล

• คุณคือใคร: แพลตฟอร์ม พร็อกซี หรือ "Model Gardens" ภายในที่ ปรับการเข้าถึงให้เป็นมาตรฐานในผู้ให้บริการ LLM ที่แตกต่างกันหลายราย (เช่น OpenAI, Anthropic, Google) ให้เป็นอินเทอร์เฟซเดียว
• เป้าหมาย: ความสามารถในการพกพาและความสม่ำเสมอ

เกตเวย์ขององค์กร

• คุณคือใคร: ทีมวิศวกรรมแพลตฟอร์มภายในของบริษัทขนาดใหญ่ ที่สร้าง "เส้นทางทอง" สำหรับนักพัฒนาซอฟต์แวร์ภายในหลายร้อยคน
• เป้าหมายของคุณ: การกำหนดมาตรฐาน การกำกับดูแล และการตรวจสอบสิทธิ์แบบรวม

เปรียบเทียบข้อมูลโดยย่อ

แนวทางปฏิบัติแนะนำระดับโลก: พาร์ทเนอร์ทุกรายต้องส่งส่วนหัว x-goog-api-client ไม่ว่าเส้นทางที่เลือกจะเป็นเส้นทางใดก็ตาม

การผสานรวม Google GenAI SDK

สำหรับเฟรมเวิร์ก การใช้ Google GenAI SDK มักจะเป็นเส้นทางที่ง่ายที่สุด เนื่องจากมีโค้ดน้อยที่สุดในภาษาที่รองรับ

สำหรับทีมแพลตฟอร์มภายใน สิ่งที่คุณต้องส่งมอบเป็นหลักมักจะเป็น "เส้นทางทอง" ที่ช่วยให้วิศวกรผลิตภัณฑ์ทำงานได้อย่างรวดเร็วในขณะที่ปฏิบัติตามนโยบายด้านความปลอดภัย

ข้อดี

• อินเทอร์เฟซแบบรวมสำหรับการย้ายข้อมูล Vertex AI: นักพัฒนาซอฟต์แวร์ภายในมักจะ สร้างต้นแบบโดยใช้คีย์ API (Gemini API) และนำไปใช้งานใน Vertex AI (IAM) เพื่อให้เป็นไปตามข้อกำหนดด้านการผลิต SDK จะสรุปความแตกต่างในการตรวจสอบสิทธิ์เหล่านี้ ในทำนองเดียวกันสำหรับเฟรมเวิร์ก คุณสามารถใช้เส้นทางการเขียนโค้ดเดียวและรองรับผู้ใช้ 2 กลุ่มได้
• ตัวช่วยฝั่งไคลเอ็นต์: SDK มีเครื่องมืออรรถประโยชน์ที่ช่วยลด โค้ดมาตรฐานสำหรับงานที่ซับซ้อน
  • ตัวอย่าง: รองรับPILออบเจ็กต์รูปภาพในพรอมต์โดยตรง การเรียกใช้ฟังก์ชันอัตโนมัติ และประเภทที่ครอบคลุม
• สิทธิ์เข้าถึงฟีเจอร์ตั้งแต่วันแรก: ฟีเจอร์ใหม่ของ API จะพร้อมใช้งานเมื่อเปิดตัว ผ่าน SDK
• การรองรับการสร้างโค้ดที่ดีขึ้น: การติดตั้ง SDK ในเครื่องจะแสดงคำจำกัดความประเภท และสตริงเอกสารต่อผู้ช่วยการเขียนโค้ด (เช่น Cursor, Copilot) บริบทนี้ช่วยปรับปรุงความแม่นยำในการสร้างโค้ดเมื่อเทียบกับการสร้างคำขอ REST ดิบ

ข้อแลกเปลี่ยน:

• น้ำหนักและความซับซ้อนของการอ้างอิง: SDK มีการอ้างอิงของตัวเอง ซึ่งอาจเพิ่มขนาดของ Bundle และความเสี่ยงในห่วงโซ่อุปทาน
• การกำหนดเวอร์ชัน: ฟีเจอร์ใหม่ของ API มักจะเชื่อมโยงกับ SDK เวอร์ชันขั้นต่ำ คุณอาจต้องพุชการอัปเดตไปยังผู้ใช้เพื่อให้เข้าถึงฟีเจอร์หรือโมเดลใหม่ๆ ซึ่งในบางกรณีอาจต้องมีการเปลี่ยนแปลงในทรัพยากร Dependency แบบทรานซิทีฟที่ ส่งผลต่อผู้ใช้
• ข้อจำกัดของโปรโตคอล: SDK รองรับเฉพาะ HTTPS สำหรับ API หลักและ WebSocket (WSS) สำหรับ Live API โดยไม่รองรับ gRPC เมื่อใช้ ไคลเอ็นต์ SDK ระดับสูง
• การรองรับภาษา: SDK รองรับภาษาปัจจุบัน หากคุณ ต้องรองรับเวอร์ชันที่สิ้นสุดการสนับสนุนแล้ว (เช่น Python 3.9) คุณจะต้องดูแลรักษา การแยก

แนวทางปฏิบัติแนะนำ

• ล็อกเวอร์ชัน: ปักหมุดเวอร์ชัน SDK ในอิมเมจพื้นฐานภายในเพื่อ ให้มั่นใจถึงความเสถียรในทีมต่างๆ

การผสานรวม API โดยตรง

หากคุณเผยแพร่ไลบรารีแก่นักพัฒนาแอปหลายพันคน, เรียกใช้ในสภาพแวดล้อมที่มีข้อจำกัด หรือสร้างตัวรวบรวมที่ต้องใช้ฟีเจอร์เวอร์ชันล่าสุดของ Gemini คุณอาจต้องผสานรวมกับ API โดยตรงโดยใช้ REST หรือ gRPC

ข้อดี

• การเข้าถึงฟีเจอร์ทั้งหมด: การใช้ API โดยตรงจะเปิดใช้ฟีเจอร์เฉพาะของ Gemini เช่น การอัปโหลดไปยัง File API, การสร้างแคชเนื้อหา และการใช้ Live API แบบ 2 ทาง ซึ่งต่างจากเลเยอร์ความเข้ากันได้ของ OpenAI
• การพึ่งพาที่น้อยที่สุด: ในสภาพแวดล้อมที่การพึ่งพามีความละเอียดอ่อนเนื่องจากขนาดหรือค่าใช้จ่ายในการตรวจสอบ การใช้ API โดยตรงผ่านไลบรารีมาตรฐาน เช่น fetch หรือผ่าน Wrapper เช่น httpx จะช่วยให้ไลบรารีของคุณมีขนาดเล็ก
• ไม่ขึ้นอยู่กับภาษา: นี่เป็นเส้นทางเดียวสำหรับภาษาที่ SDK ไม่รองรับ เช่น Rust, PHP และ Ruby เนื่องจากไม่มีข้อจำกัดด้านภาษา
• ประสิทธิภาพ: Direct API ไม่มีค่าใช้จ่ายในการเริ่มต้น ซึ่งช่วยลด การเริ่มต้นแบบเย็นในฟังก์ชันแบบไร้เซิร์ฟเวอร์

ข้อแลกเปลี่ยน:

• การติดตั้งใช้งาน Vertex AI ด้วยตนเอง: การใช้ API โดยตรงจะ ไม่จัดการความแตกต่างในการตรวจสอบสิทธิ์ระหว่าง AI Studio (คีย์ API) กับ Vertex AI (IAM) โดยอัตโนมัติ ซึ่งแตกต่างจาก SDK คุณต้องใช้ตัวแฮนเดิลการตรวจสอบสิทธิ์แยกต่างหากหากต้องการรองรับทั้ง 2 สภาพแวดล้อม
• ไม่มีประเภทหรือตัวช่วยดั้งเดิม: คุณจะไม่ได้รับการเติมโค้ดหรือการตรวจสอบขณะคอมไพล์สำหรับออบเจ็กต์คำขอ เว้นแต่คุณจะติดตั้งใช้งานด้วยตนเอง ไม่มี "ตัวช่วย" ไคลเอ็นต์ (เช่น ตัวแปลงฟังก์ชันเป็นสคีมา) ดังนั้นคุณต้องเขียนตรรกะนี้ด้วยตนเอง

แนวทางปฏิบัติแนะนำ

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

• ปลายทาง: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

การผสานรวม OpenAI SDK

หากคุณเป็นแพลตฟอร์มที่ให้ความสำคัญกับสคีมาแบบรวม (OpenAI Chat Completions) มากกว่าฟีเจอร์เฉพาะโมเดล นี่คือเส้นทางที่เร็วที่สุดสำหรับคุณ

ข้อดี

• ใช้งานง่าย: คุณมักจะเพิ่มการสนับสนุนของ Gemini ได้โดยการเปลี่ยน baseURL และ apiKey ซึ่งเป็นวิธีที่รวดเร็วในการผสานรวมการติดตั้งใช้งาน "Bring Your Own Key" และเพิ่มการรองรับ Gemini โดยไม่ต้องเขียนโค้ดใหม่
• ข้อจำกัด: เราขอแนะนำเส้นทางนี้เฉพาะในกรณีที่คุณถูกจำกัดให้ใช้ OpenAI SDK และไม่จำเป็นต้องใช้ฟีเจอร์ขั้นสูงของ Gemini เช่น File API หรือการเพิ่มการรองรับเครื่องมือต่างๆ เช่น Grounding ด้วย Google Search ด้วยตนเอง

ข้อแลกเปลี่ยน:

• ข้อจำกัดของฟีเจอร์: เลเยอร์ความเข้ากันได้มีข้อจำกัดสำหรับ ความสามารถหลักของ Gemini เครื่องมือฝั่งเซิร์ฟเวอร์ที่ใช้ได้จะแตกต่างกันไปในแต่ละแพลตฟอร์ม และอาจต้องมีการจัดการด้วยตนเองเพื่อให้ทำงานร่วมกับเครื่องมือ Gemini API ได้
• ค่าใช้จ่ายในการแปล: เนื่องจากสคีมาของ OpenAI ไม่ได้แมปกับสถาปัตยกรรมของ Gemini แบบ 1:1 การใช้เลเยอร์ความเข้ากันได้จึงทำให้เกิดความซับซ้อนบางอย่างที่ต้องมีการติดตั้งใช้งานเพิ่มเติมเพื่อแก้ไข เช่น การแมปเครื่องมือ "ค้นหา" ของผู้ใช้กับเครื่องมือแพลตฟอร์มที่เหมาะสม หากคุณต้องการใช้การจัดการเคสพิเศษจำนวนมาก การใช้ SDK หรือ API เฉพาะสำหรับแต่ละแพลตฟอร์มอาจมีประโยชน์มากกว่า

แนวทางปฏิบัติแนะนำ

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

แนวทางปฏิบัติแนะนำสำหรับพาร์ทเนอร์ทุกราย: การระบุไคลเอ็นต์

เมื่อเรียกใช้ Gemini API ในฐานะแพลตฟอร์มหรือไลบรารี คุณต้อง ระบุไคลเอ็นต์โดยใช้ส่วนหัว x-goog-api-client

ซึ่งจะช่วยให้ Google ระบุกลุ่มการเข้าชมที่เฉพาะเจาะจงของคุณได้ และหากคลังของคุณสร้างรูปแบบข้อผิดพลาดที่เฉพาะเจาะจง เราจะติดต่อเพื่อช่วยคุณแก้ไขข้อบกพร่องได้

ใช้รูปแบบ company-product/version (เช่น acme-framework/1.2.0)

ตัวอย่างการติดตั้งใช้งาน

from google import genai

client = genai.Client(
    api_key="...",
    http_options={
        "headers": {
            "x-goog-api-client": "acme-framework/1.2.0",
        }
    }
)

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H 'x-goog-api-client: acme-framework/1.2.0' \
    -d '{...}'

from openai import OpenAI

client = OpenAI(
    api_key="...",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
    default_headers={
        "x-goog-api-client": "acme-framework-oai/1.2.0",
    }
)

ขั้นตอนถัดไป

• ไปที่ภาพรวมของไลบรารีเพื่อดูข้อมูลเกี่ยวกับ GenAI SDK
• เรียกดูเอกสารอ้างอิง API
• อ่านคู่มือความเข้ากันได้ของ OpenAI