مفاهیم اساسی هوش مصنوعی را در برنامه های چت گوگل ادغام کنید

۱. قبل از شروع

برنامه‌های گوگل چت با هوش مصنوعی چیستند؟

برنامه‌های گوگل چت با هوش مصنوعی موارد زیر را انجام می‌دهند:

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

چرا برنامه‌های گوگل چت را با هوش مصنوعی ادغام کنیم؟

موارد استفاده معمول در دسته‌های زیر قرار می‌گیرند:

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

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

پیش‌نیازها

آنچه خواهید ساخت

در این آزمایشگاه کد، شما هشت برنامه مینیمالیستی گوگل چت خواهید ساخت که مفاهیم اساسی هوش مصنوعی را ادغام می‌کنند تا نشان دهند که چگونه می‌توان آنها را در برنامه‌های دنیای واقعی به کار برد. همه آنها به عنوان افزونه‌های Google Workspace ساخته شده‌اند و بر معماری HTTP متکی هستند:

2f1e2c66f6e2e2f0.png

به شرح زیر عمل می‌کند:

  1. کاربر پیامی را در Google Chat به یک برنامه چت، چه به صورت پیام مستقیم و چه در فضای چت، ارسال می‌کند.
  2. یک درخواست HTTP به سرور وب که به عنوان یک تابع Node.js Google Cloud Run که شامل منطق برنامه چت است، اجرا می‌شود، ارسال می‌شود.
  3. به صورت اختیاری، منطق برنامه چت می‌تواند با سرویس‌های Google Workspace (مانند Calendar و Sheets)، سایر سرویس‌های گوگل (مانند Maps، YouTube و Vertex AI) یا سایر سرویس‌های وب (مانند سیستم مدیریت پروژه یا ابزار تیکتینگ) ادغام شود.
  4. وب سرور یک پاسخ HTTP را به سرویس برنامه چت در Chat ارسال می‌کند.
  5. پاسخ به کاربر تحویل داده می‌شود.
  6. به صورت اختیاری، برنامه چت می‌تواند API چت را برای ارسال پیام‌ها یا انجام سایر عملیات به صورت غیرهمزمان فراخوانی کند.

تابع Node.js Google Cloud Run هر برنامه چت گوگل شامل نسخه مخصوص به خود از فایل‌های منبع زیر است تا اقدامات لازم در مراحل ۳ و ۶ بالا را انجام دهد:

  • package.json : یک فایل مانیفست مرکزی که به عنوان طرح اولیه برای پروژه Node.js عمل می‌کند. از آن برای تعریف متادیتا، وابستگی‌ها و اسکریپت‌ها استفاده می‌شود.
  • env.js : اسکریپتی که ثابت‌های مورد نیاز برای اجرا را تنظیم می‌کند. این اسکریپت باید بر اساس محیط و پیکربندی ویرایش شود.
  • index.js: اسکریپت اصلی که منطق رویدادهای تعاملی گوگل چت را مدیریت می‌کند. فقط نوع رویداد پیام در این آزمایشگاه کد پیاده‌سازی شده است، اما معمولاً شامل انواع دیگری مانند کلیک کارت، دستور اسلش و دیالوگ در برنامه‌های واقعی نیز می‌شود.

برنامه سریع

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

5975b36968ab597a.gif

برنامه فرمت

این برنامه با افزودن پشتیبانی از پاسخ‌های متنی غنی مطابق با قالب متنی خاص پیام‌های Google Chat، بر اساس Prompt app ساخته شده است.

bc49e0acf0838f28.gif

برنامه زمینی

این برنامه با اضافه کردن پشتیبانی از ابزار جستجوی گوگل و بازگرداندن منابع در پیام‌های پاسخ با کارت‌ها، بر اساس Format app ساخته شده است.

3cf232bf153f6abc.gif

برنامه MCP

این برنامه با افزودن پشتیبانی از پروتکل زمینه مدل دستیار توسعه‌دهنده Google Workspace (MCP) بر اساس Format app ساخته شده است.

8219c29366e9120e.gif

برنامه چند نوبتی

این برنامه با افزودن پشتیبانی از حافظه محاوره‌ای با پایگاه داده Google Cloud Firestore، بر اساس Format app ساخته شده است.

a819c274ce586451.gif

برنامه ابزار سفارشی

این برنامه بر اساس Multi-turn app ساخته شده است و پشتیبانی از یک ابزار سفارشی فراخوانی تابع را اضافه می‌کند که API تقویم فضای کاری گوگل را بر اساس اطلاعات ارائه شده توسط کاربر فراخوانی می‌کند.

a1c4f586b7ab2e24.gif

برنامه استریم

این برنامه برای تولید داستان‌های کوتاه بر اساس مضامین ارائه شده توسط کاربران، به مدل Gemini متکی است. از API چت گوگل برای ارسال نتایج و وضعیت‌ها در پیام‌ها همزمان با پیشرفت کار استفاده می‌شود.

fd347ba03fe86e22.gif

اپلیکیشن چندوجهی

این برنامه برای ویرایش تصاویر بر اساس دستورالعمل‌های متنی کاربران، به مدل Gemini متکی است. از APIهای Google Chat برای دانلود و آپلود تصاویر به عنوان پیوست پیام استفاده می‌شود.

57574be33474bbc.gif

آنچه یاد خواهید گرفت

  • مفاهیم اساسی هوش مصنوعی مربوط به برنامه‌های چت گوگل و نحوه‌ی به‌کارگیری آن‌ها هستند.
  • برای دسترسی به Vertex AI با استفاده از Google Gen AI SDK.
  • برای استفاده از APIهای Google Workspace برای توسعه ویژگی‌های جذاب و قدرتمند.
  • برای استفاده از Cloud Run جهت ساخت برنامه‌های مقیاس‌پذیر Google Chat.

آنچه شما نیاز خواهید داشت

  • تکمیل شروع سریع ساخت یک برنامه HTTP Google Chat با Node.js. این آزمایشگاه کد بر اساس پروژه Google Cloud حاصل، برنامه Google Chat و تابع Google Cloud Run ساخته شده است.

۲. آماده شوید

مقداردهی اولیه و دسترسی به منابع

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

پیکربندی API گوگل چت

کنسول گوگل کلود را در یک تب جدید باز کنید، سپس این مراحل را دنبال کنید:

  1. پروژه خود را انتخاب کنید.
  2. در فیلد جستجوی Google Cloud، عبارت «Google Chat API» را جستجو کنید، سپس روی Google Chat API کلیک کنید، روی مدیریت کلیک کنید و در نهایت روی پیکربندی کلیک کنید.

  1. نام و توضیحات برنامه را روی Gen AI App تنظیم کنید.
  2. روی ذخیره کلیک کنید.

9a06649cf9285b99.png

فضای چت گوگل

گوگل چت را در یک تب جدید باز کنید، سپس این مراحل را دنبال کنید:

  1. اگر قبلاً این کار را نکرده‌اید، یک فضای پیام مستقیم با برنامه چت باز کنید.
  2. عبارت Hello را تایپ کنید و enter بزنید، برنامه چت باید با نام و تصویر آواتار شما پاسخ دهد.

e3b195c7b7b8e2af.png

سرویس عملکرد Google Cloud Run

کنسول گوگل کلود را در یک تب جدید باز کنید، سپس این مراحل را دنبال کنید:

  1. پروژه خود را انتخاب کنید.
  2. روی منو ☰ > Cloud Run > سرویس‌ها کلیک کنید.

  1. در فهرست سرویس‌ها، روی addonchatapp کلیک کنید، سپس تب Source را باز کنید.

b69df34ea0dc48a5.png

دانلود کد منبع و منابع به صورت محلی

  1. این مخزن گیت‌هاب را دانلود کنید.

  1. در محیط توسعه محلی مورد نظر خود، پوشه node/chat/gen-ai-apps را باز کنید.

3c57c15db4ebfddb.png

۳. برنامه سریع

این برنامه، Gemini را در Vertex AI وادار می‌کند تا با استفاده از پاسخ‌های مختصر و متنی ساده، با کاربران به زبان طبیعی خودشان صحبت کند. پیاده‌سازی این برنامه بر اساس Google Gen AI SDK برای Node.js انجام شده است.

مفاهیم را مرور کنید

زبان طبیعی

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

عملکردهای Cloud Run

توابع Cloud Run برای ساخت backend های بدون سرور، انجام پردازش داده‌های بلادرنگ و ایجاد برنامه‌های هوشمند عالی هستند. هیچ سروری برای تهیه، مدیریت، وصله کردن یا به‌روزرسانی وجود ندارد. آنها به طور خودکار مقیاس‌پذیر هستند و در دسترس بودن بالایی دارند و در برابر خطا مقاوم هستند.

ترغیب

راهنمایی به تکنیک ایجاد ورودی (راهنماها) برای هدایت یک مدل هوش مصنوعی مولد برای تولید خروجی مطلوب اشاره دارد. این کار معمولاً شامل بیان دقیق سوالات، ارائه زمینه، ارائه دستورالعمل‌ها یا ارائه مثال‌هایی برای دریافت پاسخ‌های خاص و مرتبط از مدل است.

هوش مصنوعی ورتکس

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

c9e9c7a1945b22ac.png

جوزا

Gemini یک دوره کارشناسی ارشد مدیریت چندوجهی از گوگل است که از طریق Vertex AI قابل دسترسی است. این دوره به افراد کمک می‌کند تا پتانسیل انسانی خود را شکوفا کنند تا بتوانند تخیل خود را تقویت کنند، کنجکاوی خود را گسترش دهند و بهره‌وری خود را افزایش دهند.

کیت توسعه نرم‌افزاری هوش مصنوعی نسل گوگل (Google Gen AI SDK)

کیت توسعه نرم‌افزاری هوش مصنوعی گوگل (Google Gen AI SDK) برای توسعه‌دهندگان طراحی شده است تا بتوانند برنامه‌هایی را با پشتیبانی Gemini بسازند. این کیت رابط کاربری یکپارچه‌ای را ارائه می‌دهد که با API توسعه‌دهندگان Gemini و Vertex AI سازگار است. این کیت با کتابخانه‌های کلاینت در پایتون ، گو ، نودجی‌اس و جاوا ارائه می‌شود.

جریان بررسی

c625fdcc8b4a27f4.png

بررسی کد منبع

env.js 

...
// Replace with your GCP project ID.
projectID: process.env.PROJECT_ID || 'your-google-cloud-project-id',

// Replace with your GCP project location.
location: process.env.LOCATION || 'your-google-cloud-project-location',

// Replace with the Gemini model to use.
model: process.env.MODEL || 'gemini-2.5-flash-lite',
...

ایندکس.js 

// Import the Google Gen AI SDK.
import { GoogleGenAI } from '@google/genai';
...
// Use Vertex AI.
const genAI = new GoogleGenAI({vertexai: true, project: env.projectID, location: env.location});

http('gen-ai-app', async (req, res) => {
 // Send a new Chat message with the generated answer
 return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
   text: await generateAnswer(req.body.chat.messagePayload.message.text)
 }}}}});
});

async function generateAnswer(message) {
 // The prompt is made of the user's message and specific instructions for the model.
 const prompt = 'In a consice and with plain text only (no formatting), '
                 + 'answer the following message in the same language: ' + message;
 const aiResponse = await genAI.models.generateContent({model: env.model, contents: prompt});
 return aiResponse.candidates[0].content.parts[0].text;
};
...

بسته.json 

...
"main": "index.js",
"type": "module",
"scripts": {
  "start": "node index.js"
},
"dependencies": {
  "@google-cloud/functions-framework": "^4.0.0",
  "@google/genai": "1.15.0"
},
...

فعال کردن API هوش مصنوعی ورتکس

  1. در کنسول Google Cloud ، رابط برنامه‌نویسی کاربردی Vertex AI را فعال کنید:

  1. روی منو ☰ > APIها و خدمات > APIها و خدمات فعال‌شده کلیک کنید و سپس تأیید کنید که Vertex AI API در لیست قرار دارد.

به‌روزرسانی تابع Google Cloud Run Node.js

  1. در محیط توسعه محلی خود، دایرکتوری فعلی را به node/chat/gen-ai-apps/1-prompt تغییر دهید. این دایرکتوری شامل کل کد منبع و منابع است.
  2. env.js در یک ویرایشگر باز کنید و موارد زیر را تنظیم کنید:
  3. projectID : شناسه پروژه گوگل کلود شما. می‌توانید آن را از صفحه خوشامدگویی کنسول گوگل کلود بازیابی کنید.

  1. مکان : منطقه سرویس عملکرد Google Cloud Run شما. می‌توانید آن را از صفحه جزئیات سرویس عملکرد Google Cloud Run بازیابی کنید.

  1. مدل : مدلی که باید استفاده شود. می‌توانید تمام مدل‌های موجود را از مستندات Vertex AI پیدا کنید. مدل پیش‌فرض برای اجرای سریع و ارزان، Flash است.

6c2fb9f554f53a4a.png

  1. به برگه منبع (Source) در صفحه جزئیات سرویس عملکرد Google Cloud Run بروید.

  1. روی ویرایش منبع کلیک کنید.
  2. نقطه ورود تابع را روی gen-ai-app تنظیم کنید.
  3. روی ➕ کلیک کنید، env.js را تایپ کنید و برای ایجاد فایل منبع گمشده، روی ✔️ کلیک کنید.
  4. کل محتویات فایل‌های index.js ، env.js و package.json را با محتویات موجود در محیط توسعه محلی خود جایگزین کنید.
  5. روی ذخیره و استقرار مجدد کلیک کنید.
  6. منتظر اتمام موفقیت‌آمیز استقرار نسخه اصلاح‌شده باشید.

487b64f2d3b1a104.png

امتحانش کن

  1. در فضای پیام مستقیم با برنامه چت در گوگل چت ، عبارت Hello, how are you? را تایپ کنید و enter بزنید. برنامه باید طبق دستورالعمل‌های ما در پیام، به طور مختصر و با متن ساده پاسخ دهد.

3cc1fd1de2a9e239.png

  1. در فضای پیام مستقیم با برنامه چت در Google Chat ، عبارت Bonjour comment allez-vous? را تایپ کنید و enter را فشار دهید. برنامه باید طبق دستورالعمل‌های ما در اعلان، به زبان فرانسوی پاسخ دهد.

77010f4ad0bde5da.png

۴. فرمت کردن برنامه

این برنامه با افزودن پشتیبانی از پاسخ‌های متنی غنی مطابق با قالب پیام متنی گوگل چت، بر اساس Prompt app ساخته شده است. دستورالعمل‌های موجود در اعلان با شرح کاملی از گزینه‌های مختلفی که مدل می‌تواند استفاده کند، به‌روزرسانی شده‌اند.

مفاهیم را مرور کنید

پیام‌های متنی گوگل چت

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

جریان بررسی

c625fdcc8b4a27f4.png

بررسی کد منبع

ایندکس.js 

...
async function generateAnswer(message) {
 // Specify formatting options that are compatible with Google Chat messages
 // https://developers.google.com/workspace/chat/format-messages#format-texts
 const prompt = `Use simple text for concise answers. The only formatting options you can use is to
(1) surround some text with a single star for bold such as *text* for strong emphasis
(2) surround some text with a single underscore for italic such as _text_ for gentle emphasis
(3) surround some text with a single tild for strikethrough such as ~text~ for removal
(4) use a less than before followed by a URL followed by a pipe followed by a link text followed
    by a more than for a hyperlink such as <https://example.com|link text> for resource referencing
(5) use a backslash followed by the letter n for a new line such as \n for readibility
(6) surround some text with a single backquote such as \`text\` for quoting code
(7) surround an entire paragraph with three backquotes in dedicated lines such as
    \`\`\`\nparagraph\n\`\`\` for quoting code
(8) prepend lines with list items with a single star or hyphen followed by a single space
    such as * list item or - list item for bulleting ;
DO NOT USE ANY OTHER FORMATTING OTHER THAN THOSE.
Answer the following message in the same language: ${message}`;
...
};
...

به‌روزرسانی تابع Google Cloud Run Node.js

  1. در محیط توسعه محلی خود، دایرکتوری فعلی را به node/chat/gen-ai-apps/2-format تغییر دهید. این دایرکتوری شامل کل کد منبع و منابع است.
  2. به برگه منبع (Source) در صفحه جزئیات سرویس عملکرد Google Cloud Run بروید.

  1. روی ویرایش منبع کلیک کنید.
  2. کل محتوای فایل index.js را با محتوای موجود در محیط توسعه محلی خود جایگزین کنید.
  3. روی ذخیره و استقرار مجدد کلیک کنید.
  4. منتظر اتمام موفقیت‌آمیز استقرار نسخه اصلاح‌شده باشید.

487b64f2d3b1a104.png

امتحانش کن

  1. در فضای پیام مستقیم با برنامه چت در گوگل چت ، عبارت Showcase all formatting options you have with one paragraph each و enter را بزنید. برنامه باید بر اساس دستورالعمل‌های ما در اعلان، نمونه‌های قالب‌بندی را ارائه دهد.

cc7f7101d9f7c10.png

  1. در فضای پیام مستقیم با برنامه چت در Google Chat ، عبارت What are Google Chat apps? What's great about them? را تایپ کنید و enter را فشار دهید. برنامه باید در صورت لزوم با قالب‌بندی پاسخ دهد.

۸۳۵۵۷d4c7071aac8.png

۵. برنامه زمینی

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

مفاهیم را مرور کنید

اتصال زمین

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

ابزار جستجوی گوگل

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

چارچوب کارت فضای کاری گوگل

چارچوب کارت در Google Workspace به توسعه‌دهندگان امکان می‌دهد رابط‌های کاربری غنی و تعاملی ایجاد کنند. این چارچوب امکان ساخت کارت‌های سازمان‌یافته و بصری جذاب را فراهم می‌کند که می‌توانند شامل متن، تصاویر، دکمه‌ها و سایر ابزارک‌ها باشند. این کارت‌ها با ارائه اطلاعات ساختاریافته و فعال کردن اقدامات سریع مستقیماً در مکالمه، تجربه کاربر را بهبود می‌بخشند.

جریان بررسی

b72d69a6e79858d6.png

بررسی کد منبع

ایندکس.js 

...
const aiResponse = await genAI.models.generateContent({
 model: env.model,
 contents: prompt,
 // Google Search tool is enabled
 config: { tools: [{ googleSearch: {}}]}
});

let groundingCardsV2 = undefined;
const grounding = aiResponse.candidates[0].groundingMetadata;
// Go through the grounding metadata if any
if (grounding && grounding.groundingChunks && grounding.groundingChunks.length > 0) {
 let linkButtons = [];
 grounding.groundingChunks.forEach(groundingChunk => {
   if (groundingChunk.web) {
     // Create one link button per web URL returned
     linkButtons.push({
       text: groundingChunk.web.domain,
       onClick: { openLink: { url: groundingChunk.web.uri}}
     });
   }
 });
 // Create a card with link buttons
 groundingCardsV2 = [{
   cardId: "sourcesCard",
   card: { sections: [{
     header: "Sources",
     widgets: [{ buttonList: { buttons: linkButtons}}]
   }]}
 }];
}

// Send a Chat message with the generated answer
return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
 text: aiResponse.candidates[0].content.parts[0].text,
 // The sources are referenced in the card
 cardsV2: groundingCardsV2
}}}}});
...

به‌روزرسانی تابع Google Cloud Run Node.js

  1. در محیط توسعه محلی خود، دایرکتوری فعلی را به node/chat/gen-ai-apps/3-ground تغییر دهید. این دایرکتوری شامل کل کد منبع و منابع است.
  2. به برگه منبع (Source) در صفحه جزئیات سرویس عملکرد Google Cloud Run بروید.

  1. روی ویرایش منبع کلیک کنید.
  2. کل محتوای فایل index.js را با محتوای موجود در محیط توسعه محلی خود جایگزین کنید.
  3. روی ذخیره و استقرار مجدد کلیک کنید.
  4. منتظر اتمام موفقیت‌آمیز استقرار نسخه اصلاح‌شده باشید.

487b64f2d3b1a104.png

امتحانش کن

در فضای پیام مستقیم با برنامه چت در گوگل چت ، عبارت What's the world population? را تایپ کنید و enter را فشار دهید. برنامه باید با پیوست کردن لینک‌های منبع در یک کارت، پاسخ دهد.

cff461da29c05873.png

6. اپلیکیشن MCP

این برنامه با افزودن پشتیبانی از ابزارهای ارائه شده توسط سرور Model Context Protocol (MCP) که از راه دور میزبانی می‌شود، بر اساس Format app ساخته شده است. این برنامه به Google Workspace Developer Assist MCP متصل می‌شود که ابزارهایی برای دسترسی و جستجوی اسناد Google Workspace Developers ارائه می‌دهد.

مفاهیم را مرور کنید

پروتکل زمینه مدل (MCP)

پروتکل زمینه مدل (Model Context Protocol) یک چارچوب متن‌باز است که مدل‌ها را به روشی استاندارد با سرویس‌های خارجی ادغام می‌کند. مدل‌ها می‌توانند به صورت برنامه‌نویسی‌شده ابزارهای مختلف را کشف، درک و با آنها تعامل داشته باشند، قابلیت‌های خود را گسترش دهند، اقدامات دنیای واقعی را انجام دهند و به اطلاعات به‌روز شده دسترسی پیدا کنند.

کیت توسعه نرم‌افزاری تایپ‌اسکریپت MCP

کیت توسعه نرم‌افزار TypeScript مشخصات کامل MCP را پیاده‌سازی می‌کند و ایجاد کلاینت‌های MCP که به هر سرور MCP متصل می‌شوند را ساده می‌کند. همچنین امکان توسعه سرورهای MCP را فراهم می‌کند که دسترسی به منابع، اعلان‌ها و ابزارها را فراهم می‌کنند.

جریان بررسی

e0b324e2cca21915.png

بررسی کد منبع

ایندکس.js 

// Import the MCP TypeScript SDK.
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
...
// Create and connect the MCP client from the URL.
const mcpServerUrl = new URL("https://workspace-developer.goog/mcp");
const client = new Client({ name: "gen-ai-app-mcp", version: "1.0.0" });
// Try Streamable HTTP first (new) and SSE (old) as fallback for transport
try {
 await client.connect(new StreamableHTTPClientTransport(mcpServerUrl));
} catch (error) {
 await client.connect(new SSEClientTransport(mcpServerUrl));
}

http('gen-ai-app', async (req, res) => {
 ...
 const aiResponse = await genAI.models.generateContent({
   model: env.model,
   contents: prompt,
   // MCP tools are enabled
   config: { tools: [mcpToTool(client)]}
 });
 ...
}
...

بسته.json 

...
"dependencies": {
  ...
  "@modelcontextprotocol/sdk": "^1.18.1"
},
...

به‌روزرسانی تابع Google Cloud Run Node.js

  1. در محیط توسعه محلی خود، دایرکتوری فعلی را به node/chat/gen-ai-apps/4-mcp تغییر دهید. این دایرکتوری شامل کل کد منبع و منابع است.
  2. به برگه منبع (Source) در صفحه جزئیات سرویس عملکرد Google Cloud Run بروید.

  1. روی ویرایش منبع کلیک کنید.
  2. کل محتویات فایل‌های index.js و package.json را با محتویات موجود در محیط توسعه محلی خود جایگزین کنید.
  3. روی ذخیره و استقرار مجدد کلیک کنید.
  4. منتظر اتمام موفقیت‌آمیز استقرار نسخه اصلاح‌شده باشید.

487b64f2d3b1a104.png

امتحانش کن

  1. در فضای پیام مستقیم با برنامه چت در گوگل چت ، عبارت What can you do for me? را تایپ کنید و enter را فشار دهید. برنامه باید توانایی‌های خود را شرح دهد (ابزارهای MCP).

۱۳۵۳۵bfd31d85a50.png

  1. در فضای پیام مستقیم با برنامه چت در Google Chat ، عبارت I would like to get the latest official documentation for the Google Sheets API append values و enter را فشار دهید. برنامه باید با مستندات درخواستی (با استفاده از ابزارهای MCP) پاسخ دهد.

8a6f4ac5b7d5fa4a.png

۷. اپلیکیشن چند نوبتی

این برنامه با اضافه کردن پشتیبانی از حافظه مکالمه‌ای با ردیابی تاریخچه تعاملات چت، بر اساس Format app ساخته شده است. این برنامه یک تجربه طبیعی‌تر، هوشمندتر و شخصی‌سازی‌شده‌تر را فراهم می‌کند. این برنامه از پایگاه داده پیش‌فرض Google Cloud Firestore مرتبط با پروژه Google Cloud آنها برای ذخیره‌سازی استفاده می‌کند.

مفاهیم را مرور کنید

چند نوبتی

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

گوگل کلود فایر استور

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

جریان بررسی

52920a2227467218.png

بررسی کد منبع

ایندکس.js 

// Import the Google Cloud Firestore client library.
import { Firestore } from '@google-cloud/firestore';
...
// Configure DB
const USERS_PREFIX = 'users/';
const CHATS_COLLECTION = 'chats';
const db = new Firestore();
...
// Create or update data for a given user
async function createOrUpdateChatHistory(userId, data) {
 await db.collection(CHATS_COLLECTION).doc(userId.replace(USERS_PREFIX, '')).set(data);
};

// Retrieve data snapshot for a given user
async function getChatHistory(userId) {
 return await db.collection(CHATS_COLLECTION).doc(userId.replace(USERS_PREFIX, '')).get();
};
...

...
http('gen-ai-app', async (req, res) => {
 // Retrieve the chat history of the user
 const chatHistory = await getChatHistory(userId);
 const chat = genAI.chats.create({
   model: env.model,
   // Initiate the model with chat history for context
   history: chatHistory.exists ? chatHistory.data().contents : []
 });
 // If no history, send a first message to the model with instructions on how to behave
 if(!chatHistory.exists) {
   const preambule = 'The only formatting options you can use is to '
                   + ...
                   + 'DO NOT USE ANY OTHER FORMATTING OTHER THAN THOSE. '
                   + 'Answer in the same language that I use.';
   // The answer to this message is ignored
   await chat.sendMessage({message: preambule});
 }

 // Send the user's message to the model to generate the answer
 const aiResponse = await chat.sendMessage({message: userMessage});

 // Persist the updated chat history of the user
 await createOrUpdateChatHistory(userId, {contents: chat.getHistory({curated: true})});

 // Send a Chat message with the generated answer
 return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
   text: aiResponse.candidates[0].content.parts[0].text
 }}}}});
});
...

بسته.json 

...
"dependencies": {
  ...
  "@google-cloud/firestore": "^7.11.5"
},
...

فعال کردن API گوگل کلود فایراستور

  1. در کنسول Google Cloud ، API مربوط به Google Cloud Firestore را فعال کنید:

  1. روی منو ☰ > APIها و خدمات > APIها و خدمات فعال‌شده کلیک کنید و سپس تأیید کنید که API Cloud Firestore در لیست قرار دارد.

ایجاد پایگاه داده Cloud Firestore

  1. در کنسول گوگل کلود ، روی منو ☰ > فایر استور کلیک کنید

  1. روی ایجاد یک پایگاه داده Firestore کلیک کنید
  2. تنظیمات پیش‌فرض را رها کنید و روی ایجاد پایگاه داده کلیک کنید.

به‌روزرسانی تابع Google Cloud Run Node.js

  1. در محیط توسعه محلی خود، دایرکتوری فعلی را به node/chat/gen-ai-apps/5-multi-turn تغییر دهید. این دایرکتوری شامل کل کد منبع و منابع است.
  2. به برگه منبع (Source) در صفحه جزئیات سرویس عملکرد Google Cloud Run بروید.

  1. روی ویرایش منبع کلیک کنید.
  2. کل محتویات فایل‌های index.js و package.json را با محتویات موجود در محیط توسعه محلی خود جایگزین کنید.
  3. روی ذخیره و استقرار مجدد کلیک کنید.
  4. منتظر اتمام موفقیت‌آمیز استقرار نسخه اصلاح‌شده باشید.

487b64f2d3b1a104.png

امتحانش کن

  1. در فضای پیام مستقیم با برنامه چت در گوگل چت ، عبارت Can you speak with the English from the 80's for now on? را تایپ کنید و enter فشار دهید. برنامه باید پاسخ مثبت دهد.

b273beda7e203b23.png

  1. در قسمت پیام مستقیم با برنامه چت در گوگل چت ، عبارت Define what Google Chat apps are in one sentence و enter بزنید. برنامه باید همچنان با انگلیسی دهه ۸۰ پاسخ دهد.

۹۱۵۶f۵۶۳c۳۶۹f۱۸۶.png

۸. اپلیکیشن ابزار سفارشی

این برنامه با افزودن پشتیبانی از یک ابزار سفارشی فراخوانی تابع که برای بازیابی رویداد بعدی از یک تقویم عمومی به API تقویم فضای کاری گوگل متکی است، بر اساس Multi-turn app ساخته شده است. این مدل تمام تعاملات کاربر، از جمله دریافت ورودی و ارائه خروجی از ابزار را مدیریت می‌کند. با این حال، برنامه همچنان مسئول اجرای فراخوانی‌های API لازم و ارائه نتایج به مدل در صورت درخواست است. این برنامه از یک کلید API گوگل استفاده می‌کند زیرا نیازی به اعتبارنامه کاربر برای دریافت داده‌های تقویم عمومی نیست.

مفاهیم را مرور کنید

فراخوانی تابع

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

رابط‌های برنامه‌نویسی کاربردی (API) گوگل ورک‌اسپیس

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

جریان بررسی

ed866ca369a4512f.png

بررسی کد منبع

env.js 

...
// Replace with your Google API key.
googleApiKey: process.env.GOOGLE_API_KEY || 'your-google-api-key',
...

ایندکس.js 

// Import parameter type definitions from Google Gen AI SDK.
import { GoogleGenAI, Type } from '@google/genai';
// Import Google APIs that include the Google Calendar API.
import { google } from 'googleapis';
...
// Create a Google Calendar API client using a Google API key.
const calendar = google.calendar({version: 'v3', auth: env.googleApiKey});
...
// Define the tool used for function calling
const getNextPublicCalendarEventTitleFunctionDeclaration = {
 name: 'getNextPublicCalendarEventTitle',
 parameters: {
   type: Type.OBJECT,
   description: 'Get the title of the next event of a public calendar.',
   properties: {
     calendarId: {
       type: Type.STRING,
       description: 'ID of the public calendar to get the next event title.',
     }
   },
   required: ['calendarId']
 }
};

// The function referenced in the tool definition
async function getNextPublicCalendarEventTitle(calendarId) {
 // Use Calendar API to retrieve the next event in the given calendar
 const response = await calendar.events.list({
   calendarId: calendarId,
   timeMin: new Date().toISOString(),
   maxResults: 1,
   singleEvents: true,
   orderBy: 'startTime',
 });
 const events = response.data.items;
 if (!events || events.length === 0) {
   return null;
 }
 return `${events[0].summary}`;
};
...

...
http('gen-ai-app', async (req, res) => {
 ...
 // Send the user's message to the model to generate the answer
 let aiResponse = await chat.sendMessage({
   message: userMessage,
   // The tool used for function calling is enabled
   config: { tools: [{ functionDeclarations: [getNextPublicCalendarEventTitleFunctionDeclaration]}]}
 });

 // Handle the function calling turn with the model if any
 const functionCall = aiResponse.candidates[0].content.parts[0].functionCall;
 if (functionCall) {
   let functionResult = null;
   switch(functionCall.name) {
     case 'getNextPublicCalendarEventTitle':
       // Make the function call as per model request
       functionResult = await getNextPublicCalendarEventTitle(functionCall.args['calendarId']);
       break;
     default:
   }
   // Finish the function calling turn by sending the execution result to the model
   aiResponse = await chat.sendMessage({ message: { functionResponse: {
     name: functionCall.name,
     response: { output: functionResult }
   }}});
 }
 ...
 // Send a Chat message with the generated answer
 return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
   text: aiResponse.candidates[0].content.parts[0].text
 }}}}});
});
...

بسته.json 

...
"dependencies": {
  ...
   "googleapis": "^160.0.0"
},
...

فعال کردن API تقویم

  1. در کنسول Google Cloud ، رابط برنامه‌نویسی کاربردی تقویم گوگل (Google Calendar API) را فعال کنید:

  1. روی منو ☰ > APIها و خدمات > APIها و خدمات فعال‌شده کلیک کنید و سپس تأیید کنید که API تقویم گوگل در لیست قرار دارد.

ایجاد کلید API گوگل

در کنسول گوگل کلود ، مراحل زیر را دنبال کنید:

  1. روی منو ☰ > APIها و خدمات > اعتبارنامه‌ها کلیک کنید.

  1. روی + ایجاد اعتبارنامه کلیک کنید و سپس کلید API را انتخاب کنید.
  2. منتظر اتمام عملیات باشید.
  3. در کادر محاوره‌ای تأیید، فیلد متنی «کلید API شما» را پیدا کنید و روی «کپی در کلیپ‌بورد» کلیک کنید.

به‌روزرسانی تابع Google Cloud Run Node.js

  1. در محیط توسعه محلی خود، دایرکتوری فعلی را به node/chat/gen-ai-apps/6-custom-tool تغییر دهید. این دایرکتوری شامل کل کد منبع و منابع است.
  2. به برگه منبع (Source) در صفحه جزئیات سرویس عملکرد Google Cloud Run بروید.

  1. روی ویرایش منبع کلیک کنید.
  2. کل محتویات فایل‌های index.js و package.json را با محتویات موجود در محیط توسعه محلی خود جایگزین کنید.
  3. فایل env.js را باز کنید و موارد زیر را انجام دهید
  4. اضافه کردن googleApiKey به فیلدهای خروجی 
export const env = {
 ...
 googleApiKey: 'your-google-api-key',
};
  1. your-google-api-key با کلید API گوگل که در مرحله قبل کپی کرده‌اید، جایگزین کنید. این کلید را می‌توانید با کلیک روی نمایش کلید، از صفحه اعتبارنامه‌های Google Cloud بازیابی کنید.

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

487b64f2d3b1a104.png

امتحانش کن

  1. در تقویم گوگل ، مراحل زیر را دنبال کنید:
  2. در قسمت «سایر تقویم‌ها» ، روی + کلیک کنید، سپس روی «ایجاد تقویم جدید» کلیک کنید.
  3. تنظیم نام برای My Public Calendar
  4. روی ایجاد تقویم کلیک کنید
  5. منتظر اتمام عملیات باشید.
  6. در قسمت تنظیمات تقویم‌های من ، تقویم تازه ایجاد شده «تقویم عمومی من» را انتخاب کنید.
  7. در قسمت مجوزهای دسترسی برای رویدادها ، گزینه «در دسترس عموم قرار دادن» را انتخاب کنید و سپس در پنجره هشدار، روی تأیید کلیک کنید.
  8. در زیر مجوزهای دسترسی برای رویدادها ، از منوی کشویی کنار گزینه «در دسترس عموم قرار دادن» گزینه «مشاهده همه جزئیات رویداد» را انتخاب کنید.
  9. در زیر بخش «ادغام تقویم» ، مقدار فیلد «شناسه تقویم» را در کلیپ‌بورد کپی کنید.
  10. برای خروج از تنظیمات، روی فلش سمت چپ در گوشه بالا سمت چپ کلیک کنید.
  11. برای ایجاد یک رویداد جدید برای فردا، روی تقویم کلیک کنید، عبارت Important meeting را تایپ کنید، از منوی کشویی، My Public Calendar را انتخاب کنید، سپس روی Save کلیک کنید.
  12. در فضای پیام مستقیم با برنامه چت در گوگل چت ، عبارت When is the next meeting? را تایپ کنید و enter بزنید. برنامه باید درخواست تاریخ دقیقی کند زیرا مشخص نیست به کدام تقویم ارجاع داده می‌شود.

40383099311b0813.png

  1. در فضای پیام مستقیم با برنامه چت در گوگل چت ، شناسه تقویمی را که قبلاً کپی کرده‌اید در کلیپ‌بورد جای‌گذاری کنید و enter فشار دهید. برنامه باید با جزئیاتی درباره رویدادی که قبلاً ایجاد شده است پاسخ دهد.

4c614c7e444e3b45.png

۹. اپلیکیشن استریم

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

مفاهیم را مرور کنید

رابط برنامه‌نویسی کاربردی گوگل چت

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

پخش جریانی

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

جریان بررسی

25f9036eecd9a48b.png

بررسی کد منبع

ایندکس.js 

// Import Google Auth library used to create Google Chat API client
import { GoogleAuth } from 'google-auth-library';
...
http('gen-ai-app', async (req, res) => {
 // Use app authentication.
 // Application Default Credentials (ADC) will use the Cloud Run function's
 // default service account, we just need to specify the Chat API app auth scopes.
 const auth = new GoogleAuth({
   // Chat API app authentication scopes
   scopes: ['https://www.googleapis.com/auth/chat.bot']
 });

 // Create Chat service client with application credentials
 const chatClient = google.chat({
   version: 'v1',
   auth: await auth.getClient()
 });

 // Send a server streaming request to generate the answer
 const aiResponse = await genAI.models.generateContentStream({
   model: env.model,
   contents: `Generate a story about a ${userMessage}. `
               + `It should take 2 minutes to read it out loud.`
 });

 // Send a first Chat message to summarize what will be done
 await chatClient.spaces.messages.create({
   parent: spaceName,
   requestBody: { text: `Sure, let me work on generating a short story `
                           + `about a ${userMessage} like you requested.`}
 });

 // Go through the response chunks received from the stream
 let messageName = undefined;
 let answer = "";
 for await (const chunk of aiResponse) {
   const text = chunk.text;
   if (text) {
     // Update the answer by concatenating the response chunks
     answer += text;
     // The Chat message request body is the same for message creation and update
     const responseBody = {
       text: answer,
       accessoryWidgets: [getStatusAccessoryWidget('Generating story...', 'progress_activity')]
     }
     if (!messageName) {
       // Create a Chat message dedicated to the generated content
       const messageResponse = await chatClient.spaces.messages.create({
         parent: spaceName,
         requestBody: responseBody
       });
       messageName = messageResponse.data.name;
     } else {
       // Update the Chat message dedicated to the generated content
       await chatClient.spaces.messages.patch({
         name: messageName,
         updateMask: 'text,accessory_widgets',
         requestBody: responseBody
       });
     }
   }
 }

 // Update the accessory widget with final progress status
 await chatClient.spaces.messages.patch({
   name: messageName,
   updateMask: 'accessory_widgets',
   requestBody: {
     accessoryWidgets: [getStatusAccessoryWidget('Story is fully generated', 'check')]
   }
 });

 // Send a last Chat message to confirm it's done
 return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
   text: 'All done, I hope you like it!'
 }}}}});
});

// Create an accessory widget with progress status
function getStatusAccessoryWidget(text, icon) {
 return { buttonList: { buttons: [{
   text: text,
   icon: { materialIcon: { name: icon}},
   // This is a workaround to have the icon shown, it's not clickable
   onClick: { openLink: { url: "https://google.com"}},
   disabled: true
 }]}};
}

بسته.json 

...
"dependencies": {
  ...
   "google-auth-library": "^10.3.0"
},
...

به‌روزرسانی تابع Google Cloud Run Node.js

  1. در محیط توسعه محلی خود، دایرکتوری فعلی را به node/chat/gen-ai-apps/7-stream تغییر دهید. این دایرکتوری شامل کل کد منبع و منابع است.
  2. به برگه منبع (Source) در صفحه جزئیات سرویس عملکرد Google Cloud Run بروید.

  1. روی ویرایش منبع کلیک کنید.
  2. کل محتویات فایل‌های index.js و package.json را با محتویات موجود در محیط توسعه محلی خود جایگزین کنید.
  3. روی ذخیره و استقرار مجدد کلیک کنید.
  4. منتظر اتمام موفقیت‌آمیز استقرار نسخه اصلاح‌شده باشید.

487b64f2d3b1a104.png

امتحانش کن

در فضای پیام مستقیم با برنامه چت در گوگل چت ، turtle را تایپ کنید و enter بزنید. برنامه باید با یک پیام تأیید، داستانی که با پیشرفت کار نمایش داده می‌شود و یک پیام تأیید تکمیل، پاسخ دهد.

۱۷۶۰۰cd۱۴۹۰۹۷۲c۷.png

26af4b3d442712a5.png

۱۰. اپلیکیشن چندوجهی

این برنامه برای ویرایش تصاویر بر اساس دستورالعمل‌های متنی کاربران، به مدلی متکی است. هم کاربران و هم برنامه، تصاویر خود را به عنوان پیوست‌های پیام گوگل چت برای تبادل اضافه می‌کنند. این برنامه برای دانلود و آپلود تصاویر به صورت برنامه‌نویسی شده، به APIهای گوگل چت متکی است.

مفاهیم را مرور کنید

پیوست پیام گوگل چت

پیوست‌های پیام‌های گوگل چت ، فایل‌هایی مانند تصاویر یا ویدیوها هستند که به یک پیام گوگل چت آپلود می‌شوند. این پیوست‌ها را می‌توان به صورت برنامه‌نویسی مدیریت کرد و برنامه‌ها را قادر ساخت تا مستقیماً در مکالمات با رسانه‌های غنی تعامل داشته باشند.

نمایندگی در سطح دامنه (DWD)

نمایندگی در سطح دامنه (DWD) به یک حساب سرویس اجازه می‌دهد تا خود را به عنوان کاربران در یک دامنه Google Workspace جا بزند و به برنامه‌ها این امکان را می‌دهد که بدون نیاز به مجوز مستقیم، از طرف آن کاربران اقداماتی را انجام دهند. این قابلیت برای برنامه‌هایی که نیاز به دسترسی به داده‌های کاربر یا انجام اقداماتی (مانند آپلود پیوست‌ها در Google Chat) در زمینه کاربر دارند، حتی زمانی که کاربر به طور فعال حضور ندارد، با اعطای دسترسی گسترده به حساب سرویس در سراسر دامنه، مفید است.

جریان بررسی

74295b25761f1682.png

بررسی کد منبع

env.js 

...
// Replace with the Gemini model to use.
model: process.env.MODEL || 'gemini-2.0-flash-preview-image-generation',
...

ایندکس.js 

...
// Import byte stream management libraries.
import { Buffer } from 'buffer';
import { Readable } from 'stream';
...
// Download a Google Chat attachment as base 64 string.
async function downloadFile(appChatClient, attachmentName) {
 const response = await appChatClient.media.download({
     resourceName: attachmentName,
     alt: 'media'
   }, {
     responseType: 'stream'
 });
 const chunks = [];
 return new Promise((resolve) => {
   response.data.on('data', (chunk) => {
     chunks.push(chunk);
   });
   response.data.on('end', () => {
     const fileBuffer = Buffer.concat(chunks);
     const base64String = fileBuffer.toString('base64');
     resolve(base64String);
   });
 });
}

// Upload a base 64 string as Google Chat attachment of a space.
async function uploadFile(useChatClient, spaceName, data) {
 const filename = 'generated_image.png';
 return await userChatClient.media.upload({
   parent: spaceName,
   requestBody: { filename: filename },
   media: {
     mimeType: 'image/png',
     body: Readable.from(Buffer.from(data, 'base64'))
   }
 });
}
...

...
http('gen-ai-app', async (req, res) => {
 const userEmail = req.body.chat.user.email;
 const spaceName = req.body.chat.messagePayload.space.name;
 const userMessage = req.body.chat.messagePayload.message.text;
 const attachmentName = req.body.chat.messagePayload.message.attachment[0].attachmentDataRef.resourceName;
 const attachmentContentType = req.body.chat.messagePayload.message.attachment[0].contentType;

 // Set up app authentication used to download the attachment input
 // Application Default Credentials (ADC) will use the Cloud Run function's
 // default service account.
 const appAuth = new GoogleAuth({
   // Specify the Chat API app authentication scopes
   scopes: ['https://www.googleapis.com/auth/chat.bot']
 });
 // Create Chat service client with application credentials
 const appChatClient = google.chat({
   version: 'v1',
   auth: await appAuth.getClient()
 });

 // Send a request to generate the answer with both text and image contents
 const aiResponse = await genAI.models.generateContent({
   model: env.model,
   contents: [{
     role: 'USER',
     parts: [
       // The text content of the message
       { text: userMessage },
       // The attachment of the message is downloaded and added inline
       { inlineData: {
         data: await downloadFile(appChatClient, attachmentName),
         mimeType: attachmentContentType
       }}
     ]
   }],
   config: { responseModalities: ['TEXT', 'IMAGE']}
 });

 // Set up user impersonation authentication used to upload the attachment output
 // and send the response.
 const impersonatedUserAuth = new GoogleAuth({
   // Specify the Chat API user authentication scopes
   scopes: ['https://www.googleapis.com/auth/chat.messages'],
   keyFile: './credentials.json',
   clientOptions: {
     // Impersonate the user who sent the original message
     subject: userEmail
   }
 });
 // Create Chat service client with impersonated user credentials
 const userChatClient = google.chat({
   version: 'v1',
   auth: await impersonatedUserAuth.getClient()
 });

 let responseText = undefined;
 let responseAttachment = undefined;
 // Go through the response parts received
 for (const part of aiResponse.candidates[0].content.parts) {
   if (part.inlineData) {
     // The resulting image is retrieved inline and uploaded
     const mediaResponse = await uploadFile(userChatClient, spaceName, part.inlineData.data);
     responseAttachment = mediaResponse.data;
   } else {
     responseText = part.text;
   }
 }

 // Create a Chat message dedicated to the generated content
 await userChatClient.spaces.messages.create({
   parent: spaceName,
   requestBody: {
     text: responseText ? responseText : 'Here it is!',
     // The uploaded image is referenced as attachment
     attachment: responseAttachment ? [responseAttachment] : undefined
   }
 });

 // Send a last Chat message to confirm it's done
 return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
   text: 'Done, feel free to let me know if you need anything else!'
 }}}}});
});
...

پیکربندی حساب کاربری سرویس و استخراج کلید خصوصی

  1. حساب کاربری پیش‌فرض سرویس Cloud Run را برای مدیریت پیام‌های Google Chat برای کاربران، تفویض اختیار کنید. دستورالعمل‌های مربوط به دامنه https://www.googleapis.com/auth/chat.messages را دنبال کنید. برای بازیابی شناسه کلاینت حساب کاربری پیش‌فرض سرویس Cloud Run، این مراحل را دنبال کنید:
  2. روی منو ☰ > مدیریت و دسترسی > حساب‌های سرویس کلیک کنید

  1. روی حساب سرویس با نام حساب سرویس محاسبه پیش‌فرض کلیک کنید.
  2. بخش تنظیمات پیشرفته را گسترش دهید
  3. شناسه کلاینت را در کلیپ‌بورد کپی کنید.
  4. یک کلید خصوصی جدید برای حساب کاربری پیش‌فرض سرویس Cloud Run ایجاد و دانلود کنید.
  5. روی منو ☰ > مدیریت و دسترسی > حساب‌های سرویس کلیک کنید

  1. روی حساب سرویس با نام حساب سرویس محاسبه پیش‌فرض کلیک کنید.
  2. تب Keys را انتخاب کنید، روی Add key و سپس Create new key کلیک کنید.
  3. JSON را انتخاب کنید، سپس روی ایجاد کلیک کنید.
  4. جفت کلید عمومی/خصوصی جدید شما ایجاد و به عنوان یک فایل جدید در دستگاه شما دانلود می‌شود. فایل JSON دانلود شده را ذخیره کرده و محتوای آن را در کلیپ‌بورد کپی کنید. این فایل تنها کپی از این کلید است. برای کسب اطلاعات در مورد نحوه ذخیره ایمن کلید خود، به مدیریت کلیدهای حساب سرویس مراجعه کنید.

به‌روزرسانی تابع Google Cloud Run Node.js

  1. در محیط توسعه محلی خود، دایرکتوری فعلی را به node/chat/gen-ai-apps/8-multimodal تغییر دهید. این دایرکتوری شامل کل کد منبع و منابع است.
  2. به برگه منبع (Source) در صفحه جزئیات سرویس عملکرد Google Cloud Run بروید.

  1. روی ویرایش منبع کلیک کنید.
  2. روی ➕ کلیک کنید، credentials.json را تایپ کنید و برای ایجاد فایل منبع گمشده، روی ✔️ کلیک کنید.
  3. محتویات فایل JSON دانلود شده در مرحله قبل را در فایل credentials.json که به تازگی ایجاد شده است، جایگذاری (paste) کنید.
  4. کل محتوای فایل index.js را با محتوای موجود در محیط توسعه محلی خود جایگزین کنید.
  5. فایل env.js را باز کنید و مقدار model را روی gemini-2.0-flash-preview-image-generation تنظیم کنید. 
...
model: 'gemini-2.0-flash-preview-image-generation',
...
  1. روی ذخیره و استقرار مجدد کلیک کنید.
  2. منتظر اتمام موفقیت‌آمیز استقرار نسخه اصلاح‌شده باشید.

487b64f2d3b1a104.png

امتحانش کن

در فضای پیام مستقیم با برنامه چت در گوگل چت ، یک عکس پرتره از خودتان با فرمت PNG آپلود کنید، عبارت Change the background color to blue تایپ کنید و enter بزنید. برنامه باید با نسخه‌ای از تصویر با پس‌زمینه آبی و یک پیام تأیید تکمیل، پاسخ دهد.

270547e7a83c1841.png

۱۱. تمیز کردن

حذف پروژه گوگل کلود

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

در کنسول گوگل کلود ، مراحل زیر را دنبال کنید:

  1. روی منو ☰ > مدیریت و شناسه کاربری > تنظیمات کلیک کنید.

  1. روی خاموش کردن کلیک کنید.
  2. شناسه پروژه را وارد کنید.
  3. روی «در هر صورت خاموش شو» کلیک کنید.

407699a4e03afea6.png

۱۲. تبریک

تبریک! شما برنامه‌های گوگل چت را به عنوان افزونه‌های گوگل ورک‌اسپیس ساختید که مفاهیم اساسی هوش مصنوعی را در خود جای داده‌اند!

بعدش چی؟

ما در این آزمایشگاه کد فقط موارد استفاده مینیمالیستی را به نمایش می‌گذاریم، اما حوزه‌های توسعه زیادی وجود دارد که ممکن است بخواهید در برنامه‌های Google Chat خود در نظر بگیرید، مانند موارد زیر:

  • پشتیبانی از انواع دیگر رسانه مانند صدا و تصویر.
  • با سایر مدل‌های هوش مصنوعی، از جمله گمرک، که در پلتفرم‌های اختصاصی مانند Vertex AI میزبانی می‌شوند، ادغام شوید.
  • با نمایندگان، از جمله گمرک، که در پلتفرم‌های اختصاصی مانند Agentspace و Dialogflow CX میزبانی می‌شوند، ادغام شوید.
  • برای نظارت و بهبود عملکرد، به حلقه‌های بازخورد و طبقه‌بندی‌ها تکیه کنید.
  • برای توانمندسازی تیم‌ها، سازمان‌ها یا کاربران عمومی، در بازار منتشر کنید.

بیشتر بدانید

منابع زیادی برای توسعه‌دهندگان وجود دارد، مانند ویدیوهای یوتیوب، وب‌سایت‌های مستندات، نمونه کدها و آموزش‌ها: