۱. مرور کلی
این آزمایشگاه کد، نحوهی اجرای کوئریهای گراف روی Spanner را با استفاده از gemini-cli و سرورهای پروتکل زمینه مدل (MCP) گوگل نشان میدهد. با ادغام پایگاه داده چند مدلی Spanner شامل Spanner Graph با سرویس MCP مدیریتشده، میتوانید از زبان طبیعی برای کشف روابط پنهان در دادههای خود - مانند حلقههای کلاهبرداری یا وابستگیهای زنجیره تأمین - در یک پایگاه داده واحد بدون نوشتن کوئریهای پیچیده GQL (زبان کوئری گراف) یا SQL به صورت دستی استفاده کنید.
آنچه یاد خواهید گرفت
- نحوه راهاندازی یک پایگاه داده چند مدلی Spanner شامل نمودار Spanner برای MCP.
- نحوه اتصال رابط خط فرمان Gemini به یک نقطه پایانی سرویس Spanner از راه دور و مدیریتشده.
- نحوه استفاده از زبان طبیعی برای تولید خودکار SQL یکپارچه با GQL برای انجام پیمایش گراف و تطبیق الگو به همراه عملیات رابطهای.
- بهترین شیوهها برای ایمنسازی دادههای گراف در گردشهای کاری هوش مصنوعی
پیشنیازها
- یک پروژه ابری گوگل با قابلیت پرداخت صورتحساب.
- دسترسی به یک ترمینال (مانند Cloud Shell). به این codelab مراجعه کنید.
- رابط خط فرمان
gcloudنصب و احراز هویت شد. - دسترسی به رابط خط فرمان Gemini .
توجه: شما تمام دستورات را در یک ترمینال یونیکس اجرا خواهید کرد. لطفاً برای دسترسی به ترمینالی که به gcloud با احراز هویت مناسب دسترسی دارد، پیشنیازهای بالا را مشاهده کنید.
۲. محیط چند مدلی Spanner را تنظیم کنید
MCP مدیریتشده زمانی بهترین عملکرد را دارد که طرحواره پایگاه داده از پیش تعریف شده باشد. ما یک نمودار «تشخیص تقلب» مالی بر اساس نمونههای نمودار Spanner ایجاد خواهیم کرد.
فعال کردن APIها
export PROJECT_ID="YOUR_PROJECT_ID"
gcloud config set project ${PROJECT_ID}
# Enable Spanner's MCP endpoint
gcloud beta services mcp enable spanner.googleapis.com --project=${PROJECT_ID}
ایجاد طرحواره پایگاه داده
یک نمونه و یک پایگاه داده با جداول پایگاه داده و یک نمودار ویژگی ایجاد کنید. این طرح ، حسابها ، اشخاص و نقل و انتقالات بین آنها را ردیابی میکند.
نکته: میتوانید این دستورات DDL را از Spanner Studio اجرا کنید. لطفاً برای اطلاعات بیشتر در مورد ایجاد و پرسوجو از پایگاه داده Spanner از کنسول GCP به این لینک مراجعه کنید.
CREATE TABLE Account (
id INT64 NOT NULL,
create_time TIMESTAMP,
is_blocked BOOL,
nick_name STRING(MAX),
) PRIMARY KEY(id);
CREATE TABLE Person (
id INT64 NOT NULL,
name STRING(MAX),
birthday TIMESTAMP,
country STRING(MAX),
city STRING(MAX),
) PRIMARY KEY(id);
CREATE TABLE AccountTransferAccount (
id INT64 NOT NULL,
to_id INT64 NOT NULL,
amount FLOAT64,
create_time TIMESTAMP NOT NULL,
order_number STRING(MAX),
FOREIGN KEY(to_id) REFERENCES Account(id),
) PRIMARY KEY(id, to_id, create_time),
INTERLEAVE IN PARENT Account ON DELETE CASCADE;
CREATE TABLE PersonOwnAccount (
id INT64 NOT NULL,
account_id INT64 NOT NULL,
create_time TIMESTAMP,
FOREIGN KEY(account_id) REFERENCES Account(id),
) PRIMARY KEY(id, account_id),
INTERLEAVE IN PARENT Person ON DELETE CASCADE;
CREATE PROPERTY GRAPH FinGraph
NODE TABLES(
Account
KEY(id)
LABEL Account PROPERTIES(
create_time,
id,
is_blocked,
nick_name),
Person
KEY(id)
LABEL Person PROPERTIES(
birthday,
city,
country,
id,
name)
)
EDGE TABLES(
AccountTransferAccount
KEY(id, to_id, create_time)
SOURCE KEY(id) REFERENCES Account(id)
DESTINATION KEY(to_id) REFERENCES Account(id)
LABEL Transfers PROPERTIES(
amount,
create_time,
id,
order_number,
to_id),
PersonOwnAccount
KEY(id, account_id)
SOURCE KEY(id) REFERENCES Person(id)
DESTINATION KEY(account_id) REFERENCES Account(id)
LABEL Owns PROPERTIES(
account_id,
create_time,
id)
);
داده ها را جمع آوری کنید
درج اشخاص
INSERT INTO Person (id, name, birthday, country, city) VALUES
(1, 'Alex', '1990-01-01T00:00:00Z', 'USA', 'New York'),
(2, 'Lee', '1985-05-15T00:00:00Z', 'USA', 'San Francisco'),
(3, 'Dana', '1995-08-20T00:00:00Z', 'Canada', 'Vancouver'),
(4, 'Maria', '1992-04-15T00:00:00Z', 'USA', 'Chicago'),
(5, 'David', '1988-11-20T00:00:00Z', 'Canada', 'Toronto');
درج حسابها
INSERT INTO Account (id, create_time, is_blocked, nick_name) VALUES
(7, '2020-01-10T14:22:20.222Z', false, 'Vacation Fund'),
(16, '2020-01-28T01:55:09.206Z', true, 'Vacation Fund'),
(20, '2020-02-18T13:44:20.655Z', false, 'Rainy Day Fund'),
(25, '2023-01-15T10:00:00Z', false, 'Savings'),
(30, '2023-02-20T11:00:00Z', false, 'Checking');
پیوند دادن افراد به حسابها
INSERT INTO PersonOwnAccount (id, account_id, create_time) VALUES
(1, 7, '2020-01-10T14:22:20.222Z'),
(2, 16, '2020-01-28T01:55:09.206Z'),
(3, 20, '2020-02-18T13:44:20.655Z'),
(4, 25, '2023-01-15T10:00:00Z'),
(5, 30, '2023-02-20T11:00:00Z');
اضافه کردن نقل و انتقالات
INSERT INTO AccountTransferAccount (id, to_id, amount, create_time, order_number) VALUES
(7, 16, 300, '2024-02-28T10:00:00Z', 'ORD123'),
(7, 16, 100, '2024-02-29T11:00:00Z', 'ORD124'),
(16, 20, 300, '2024-02-29T12:00:00Z', 'ORD125'),
(20, 7, 500, '2024-02-29T13:00:00Z', 'ORD126'),
(20, 16, 200, '2024-02-29T14:00:00Z', 'ORD127'),
(7, 25, 150.75, '2024-03-01T12:00:00Z', 'ORD456'),
(25, 30, 200.00, '2024-03-02T14:30:00Z', 'ORD457'),
(30, 16, 50.25, '2024-03-03T16:00:00Z', 'ORD458');
۳. پیکربندی Gemini CLI و Spanner MCP
این آزمایشگاه به گونهای طراحی شده است که از رابط خط فرمان Gemini به عنوان عامل اصلی برای انجام اکثر اقدامات استفاده کند و اولین قدم پیکربندی آن برای کار با سرور راه دور Spanner MCP است. همچنین اکیداً توصیه میشود از آخرین نسخه رابط خط فرمان Gemini و آخرین نسخه Gemini مانند Gemini-3-pro یا Gemini-3-flash (که در حال حاضر در مرحله پیشنمایش است) استفاده کنید.
اگر از قبل آخرین نسخه Gemini CLI را دارید و آن را برای استفاده از آخرین مدلهای Gemini پیکربندی کردهاید، میتوانید از دو مرحله بعدی صرف نظر کنید و مستقیماً به مرحله ۳ بروید.
دریافت کلید API جمینی
برای استفاده از جدیدترین مدلهای Gemini در رابط خط فرمان Gemini، باید آن را با احراز هویت با کلید API پیکربندی کنید. میتوانیم کلید API را از Google AI Studio دریافت کنیم.
- به Google AI Studio بروید -> کلید API را در مرورگر خود دریافت کنید .
- در سمت راست صفحه، روی دکمهی
Create API keyکلیک کنید. - در پنجره بازشو، پروژه خود را انتخاب کنید یا اگر در آنجا قابل مشاهده نیست، آن را وارد کنید
- کلید API را ایجاد کنید.
- میتوانید با استفاده از دکمه کپی در سمت راست، کلید را کپی کنید.
کلید آماده شده است و اکنون میتوانیم از آن برای Gemini CLI استفاده کنیم.
پیکربندی رابط خط فرمان Gemini
رابط خط فرمان Gemini را میتوان از طریق فایل تنظیمات یا به صورت تعاملی با استفاده از دستور /settings پیکربندی کرد. ما میخواهیم تنظیمات ما در فایل تنظیمات حفظ شود.
ابتدا یک دایرکتوری برای پروژه خود ایجاد میکنیم. بیایید دایرکتوری را projectspannermcp بنامیم و با استفاده از دستورات زیر به آن دایرکتوری برویم.
mkdir ~/projectspannermcp
cd ~/projectspannermcp
در این دایرکتوری، یک دایرکتوری برای فایلهای پیکربندی gemini ایجاد خواهیم کرد و تمام دستورات خود را اجرا خواهیم کرد. رابط خط فرمان Gemini به طور پیشفرض از یک فایل پیکربندی محدوده کاربر و افزونههای نصب شده در دایرکتوری ~/.gemini استفاده میکند. اما ما قصد داریم پیکربندی محدوده پروژه خود را در دایرکتوری ~/projectspannermcp ایجاد کنیم. بیایید از ایجاد دایرکتوری و فایلهای پیکربندی شروع کنیم.
mkdir ~/projectspannermcp/.gemini
touch ~/projectspannermcp/.gemini/settings.json
سپس فایل ~/projectspannermcp/.gemini/settings.json را با استفاده از ویرایشگر cloud shell باز میکنیم.
edit ~/projectspannermcp/.gemini/settings.json
در پنجره ویرایشگر باز شده، پیکربندی زیر را اضافه کنید.
{
"general": {
"preferredEditor": "vscode",
"previewFeatures": true,
"sessionRetention": {
"enabled": true
}
},
"ide": {
"enabled": true,
"hasSeenNudge": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
},
"ui": {
"theme": "Default"
},
"tools": {
"shell": {
"enableInteractiveShell": false
}
}
}
پس از ویرایش فایل، میتوانید با استفاده از ctrl+s تغییرات خود را ذخیره کرده و با کلیک بر روی دکمهی Open Terminal به ترمینال بازگردید.
فایل settings.json فوق، نوع احراز هویت Gemini CLI شما را به صورت gemini-api-key تنظیم میکند و شما باید کلید را به مدل ارائه دهید. میتوانید این کار را با ایجاد یک فایل .env در دایرکتوری که میخواهید با Gemini CLI کار کنید، انجام دهید و کلید API خود را برای احراز هویت Gemini CLI به عنوان یک متغیر محیطی ذخیره کنید که هنگام شروع IDE دریافت میشود.
بیایید فایل را با استفاده از ویرایشگر Cloud Shell ویرایش کنیم
edit ~/projectspannermcp/.env
و کلید API خود را که در مرحله "دریافت کلید API Gemini" در بالا ایجاد کردهاید، ذخیره کنید.
GEMINI_API_KEY= <YOUR_API_KEY>
حالا میتوانید به ترمینال برگردید و ادامه دهید. مرحله بعدی بهروزرسانی Gemini CLI به آخرین نسخه است. نسخه موجود در Google Cloud Shell یا در محیط شما میتواند قدیمی باشد و با آخرین پیکربندیها و سرویسهای MCP به درستی کار نکند. بنابراین مهم است که Gemini CLI را به آخرین نسخه بهروزرسانی کرده و آن را راهاندازی کنید. در ترمینال، دستور زیر را اجرا کنید.
cd ~/projectspannermcp/
npm install -g @google/gemini-cli@latest
اکنون میتوانید نسخه را تأیید کنید. لطفاً در نظر داشته باشید که اگر در پوسته ابری گوگل (Google Cloud Shell) کار میکنید، هر بار که پوسته را مجدداً راهاندازی میکنید، ممکن است به نسخه قبلی بازگردد. تغییراتی که در خود رابط خط فرمان Gemini ایجاد میکنید، در پوسته ابری دائمی نیستند.
gemini --version
باید آخرین نسخه Gemini CLI (نسخه 0.27 در زمان نوشتن آزمایشگاه) را نشان دهد. میتوانید آخرین نسخه Gemini CLI را اینجا تأیید کنید. و اکنون میتوانیم آن را اجرا کنیم و مطمئن شویم که از آخرین مدل Gemini استفاده میکند. دستور زیر را در پوشه پروژه خود اجرا کنید تا Gemini CLI شروع به کار کند.
gemini
و وقتی رابط خط فرمان Gemini شروع به کار کرد، میتوانید با اجرای دستور /about در رابط، نسخه و مدل را بررسی کنید. باید چیزی شبیه به تصویر زیر دریافت کنید.
میتوانید ببینید که از جدیدترین مدل Gemini-3 استفاده میکند. مراحل زیر که پرسوجوی زبان طبیعی را نشان میدهند، نیاز به استفاده از مدل Gemini-3 دارند.
پیکربندی رابط خط فرمان Gemini برای استفاده از Spanner MCP
یک چیز دیگر هم باید به فایل settings.json اضافه کنیم. اول، از gemini cli خارج شوید (میتوانید دو بار Ctrl+C را فشار دهید).
در همان settings.json بالا، ما قصد داریم بخش مربوط به پیکربندی سرور Spanner MCP خود را اضافه کنیم. فایل کامل settings.json را در زیر آوردهایم. به بخشی که با "mcpServers" شروع میشود، توجه کنید.
{
"general": {
"preferredEditor": "vscode",
"previewFeatures": true,
"sessionRetention": {
"enabled": true
}
},
"ide": {
"enabled": true,
"hasSeenNudge": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
},
"ui": {
"theme": "Default"
},
"tools": {
"shell": {
"enableInteractiveShell": false
}
},
"mcpServers": {
"spanner": {
"httpUrl": "https://spanner.googleapis.com/mcp",
"authProviderType": "google_credentials",
"oauth": {
"scopes": ["https://www.googleapis.com/auth/spanner.admin",
"https://www.googleapis.com/auth/spanner.data"]
},
"timeout": 5000
}
},
"mcp": {
"allowed": [
"spanner"
]
}
}
قبل از رفتن به مرحله بعدی، احراز هویت کنید
gcloud auth application-default login
پس از احراز هویت، دوباره gemini-cli را اجرا کنید.
gemini
۴. تولید چند مدل شامل کوئریهای متمرکز بر گراف
بیایید با فهرست کردن نمونههای Spanner در پروژه پیکربندیشده شما شروع کنیم.
«لطفاً تمام نمونههای Spanner را در پروژه <project1> من فهرست کنید (با شناسه پروژه خودتان جایگزین کنید)»
پاسخ:
The Spanner instances in your project are:
[instance1]
«لطفاً تمام پایگاههای داده را در <instance1> فهرست کنید (با نمونه خود جایگزین کنید)»
پاسخ:
The Spanner databases in [instance1] are:
[database1]
در مرحله بعد، به gemini میگوییم که نمونه/پایگاه دادهای را که در آن دستورات DDL و دستورات درج را در بخش تنظیمات Spanner اجرا کردهاید، به خاطر بسپارد:
«فرض کنید که تمام پرسوجوها قرار است در مقابل پایگاه داده <your-db> در نمونه <your-instance> ارسال شوند، مگر اینکه خلاف آن ذکر شده باشد.»
نکته : لطفاً از نمونه/پایگاه دادهای که دستورات DDL و دستورات درج بالا را روی آن اجرا کردهاید، استفاده کنید .
پس از اتصال، مدل Gemini طرحواره گراف را درک میکند. اکنون میتوانید پیمایشهای پیچیده را با استفاده از زبان طبیعی اجرا کنید.
مدل به طور خودکار این موارد را به GQL (زبان پرس و جوی گراف) ترجمه میکند:
شناسایی ساختارهای شبکه
«ساختار گراف ویژگی «FinGraph» را شرح دهید. برچسبهای گره و یال چیست؟»
پاسخ:
Node Labels
* `Account`: Represents financial accounts.
* Properties: id, create_time, is_blocked, nick_name
* `Person`: Represents individuals.
* Properties: id, name, birthday, country, city
Edge Labels
* `Transfers`: Represents a transfer between two Account nodes.
* Source: Account
* Destination: Account
* Properties: id, to_id, amount, create_time, order_number
* `Owns`: Represents a Person owning an Account.
* Source: Person
* Destination: Account
* Properties: id, account_id, create_time
تشخیص کلاهبرداری و چرخه
«هرگونه انتقال گردشی که در آن پول از حساب A ارسال شده و در نهایت ظرف ۳ مرحله به حساب A بازگشته است را پیدا کنید.»
پاسخ:
The analysis confirms the following circular transfers where money returns to the originating account within 3 hops:
3-Hop Cycles
Money travels through two intermediate accounts before returning to the origin.
* Account 16 (Involved in multiple 3-hop paths)
* Account 20 (Involved in multiple 3-hop paths)
* Account 7 (Involved in multiple 3-hop paths)
These accounts are participating in circular flow patterns of varying lengths.
تحلیل عمیق روابط
«تمام افرادی که حسابهایی دارند که در ۲۴ ماه گذشته بیش از ۴۹۹ دلار به حسابهای متعلق به افراد مختلف ارسال کردهاند را شناسایی کنید.»
پاسخ:
Dana is the only person who owns an account that has sent more than $499 to an account owned by a different person in the last 24 months.
(Specifically, her account sent exactly $500, which is the maximum transfer amount in the database).
مسیر یابی
«کوتاهترین مسیر انتقال وجه بین شناسه حساب ۱۶ و شناسه حساب ۲۰ را پیدا کنید.»
پاسخ:
The shortest path between Account 16 and Account 20 is 1 hop.
This means there is a direct transfer from Account 16 to Account 20.
۵. تبریک میگویم!
تبریک میگویم که آزمایشگاه کد را تمام کردی.
آنچه ما پوشش دادهایم
در این آزمایشگاه کد، یاد گرفتید که چگونه gemini-cli را با سرور Spanner MCP پیکربندی کنید و کوئریهای زبان طبیعی را برای نمایش بینشها به دادههای Spanner Graph خود ارسال کنید. در اینجا خلاصهای از مراحل کلیدی آمده است:
- زیرساخت مدیریتشده: سرور راه دور Spanner MCP فعال شد و نیاز به پروکسیهای محلی یا جعبه ابزار MCP از بین رفت.
- یکپارچهسازی گراف: یک گراف با ویژگی آچار (FinGraph) با گرهها و لبهها پیکربندی شد تا روابط پیچیده را نشان دهد.
- ابزار بومی: رابط خط فرمان Gemini را مستقیماً با استفاده از یک طرح استاندارد URI به نقطه پایانی مدیریتشده Spanner متصل کرد.
- SQL و GQL زبان طبیعی: سرور را با دستورات خاص نمودار تمرین داد و به LLM اجازه داد تا پیمایشهای چندگامی و تشخیص چرخه را بدون کدنویسی دستی SQL/GQL انجام دهد.
- آمادگی سازمانی: بررسی شد که چگونه MCP مدیریتشده، مسیری مقیاسپذیر و احراز هویتشده را برای تعامل عوامل هوش مصنوعی با دادههای عملیاتی فراهم میکند.