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

คู่มือนี้สรุปกลยุทธ์ด้านสถาปัตยกรรมสำหรับการสร้างไลบรารี แพลตฟอร์ม และเกตเวย์บน 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 header ไม่ว่าคุณจะเลือกเส้นทางใดก็ตาม

การผสานการทำงานร่วมกับ Google GenAI SDK

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

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

ข้อดี

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

ข้อดีข้อเสีย

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

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

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

การผสานการทำงานร่วมกับ Direct API

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

ข้อดี

• สิทธิ์เข้าถึงฟีเจอร์ทั้งหมด: การใช้ API โดยตรงจะเปิดใช้ฟีเจอร์เฉพาะของ Gemini เช่น การอัปโหลดไปยัง File API, การสร้างการแคชเนื้อหา และการใช้ Live API แบบ 2 ทาง ซึ่งแตกต่างจากเลเยอร์ความเข้ากันได้ของ OpenAI
• ทรัพยากร Dependency น้อยที่สุด: ในสภาพแวดล้อมที่ทรัพยากร Dependency มีความละเอียดอ่อนเนื่องจากขนาดหรือค่าใช้จ่ายในการตรวจสอบ การใช้ 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) มากกว่าฟีเจอร์เฉพาะโมเดล นี่จะเป็นเส้นทางที่เร็วที่สุด

ข้อดี

• ความยุ่งยากน้อย: คุณมักจะเพิ่มการรองรับ Gemini ได้โดยการเปลี่ยน baseURL และ apiKey นี่เป็นวิธีที่รวดเร็วในการผสานการทำงานร่วมกันของการติดตั้งใช้งาน "นำคีย์ของคุณเองมา" ซึ่งจะเพิ่มการรองรับ Gemini โดยไม่ต้องเขียนโค้ดใหม่
• ข้อจำกัด: เราแนะนำให้ใช้เส้นทางนี้เฉพาะในกรณีที่คุณถูกจำกัดให้ใช้ OpenAI SDK และไม่จำเป็นต้องใช้ฟีเจอร์ขั้นสูงของ Gemini เช่น File API หรือเพิ่มการรองรับเครื่องมือต่างๆ เช่น Grounding with 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