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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

สิทธิประโยชน์

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

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

• น้ำหนักและความซับซ้อนของ Dependency: SDK มี Dependency ของตัวเอง ซึ่งอาจเพิ่มขนาดของ 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 ไม่มีค่าใช้จ่ายในการเริ่มต้นใช้งาน ซึ่งช่วยลด Cold Start ในฟังก์ชันแบบ Serverless

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

• การติดตั้งใช้งานแพลตฟอร์ม Agent ของ Gemini Enterprise ด้วยตนเอง: การใช้ API โดยตรงจะ ไม่จัดการความแตกต่างในการตรวจสอบสิทธิ์ระหว่าง AI Studio (คีย์ API) กับแพลตฟอร์ม Agent ของ Gemini Enterprise (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 หรือการเพิ่มการรองรับเครื่องมือต่างๆ เช่น การเชื่อมต่อแหล่งข้อมูลกับ 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.5-flash: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",
    }
)

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

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