Lớp học lập trình: Máy chủ MCP Spanner

1. Tổng quan

Lớp học lập trình này minh hoạ cách đưa ra các truy vấn đồ thị trên Spanner bằng gemini-cli và các máy chủ Giao thức bối cảnh mô hình (MCP) của Google. Bằng cách tích hợp cơ sở dữ liệu đa mô hình của Spanner (bao gồm cả Spanner Graph) với dịch vụ MCP được quản lý, bạn có thể sử dụng ngôn ngữ tự nhiên để khám phá các mối quan hệ ẩn trong dữ liệu của mình (chẳng hạn như vòng tròn gian lận hoặc các mối quan hệ phụ thuộc trong chuỗi cung ứng) trong một cơ sở dữ liệu duy nhất mà không cần viết các truy vấn GQL (Ngôn ngữ truy vấn đồ thị) hoặc SQL phức tạp theo cách thủ công.

Kiến thức bạn sẽ học được

Cách thiết lập cơ sở dữ liệu đa mô hình Spanner, bao gồm cả Spanner Graph cho MCP.
Cách kết nối Gemini CLI với một điểm cuối dịch vụ Spanner từ xa được quản lý.
Cách sử dụng ngôn ngữ tự nhiên để tạo SQL được tích hợp với GQL một cách tự động nhằm thực hiện các thao tác duyệt đồ thị và so khớp mẫu cùng với các thao tác quan hệ.
Các phương pháp hay nhất để bảo mật dữ liệu biểu đồ trong quy trình làm việc AI.

Điều kiện tiên quyết

Một Dự án trên Google Cloud đã bật tính năng thanh toán.
Quyền truy cập vào một cửa sổ dòng lệnh (chẳng hạn như Cloud Shell). Hãy xem lớp học lập trình này.
Đã cài đặt và xác thực giao diện dòng lệnh gcloud.
Quyền sử dụng Gemini CLI.

LƯU Ý: Bạn sẽ chạy tất cả các lệnh trong một dòng lệnh Unix. Vui lòng xem các điều kiện tiên quyết ở trên để có quyền truy cập vào một thiết bị đầu cuối có quyền truy cập vào gcloud bằng phương thức xác thực phù hợp.

2. Thiết lập Môi trường đa mô hình Spanner

MCP được quản lý hoạt động hiệu quả nhất khi giản đồ cơ sở dữ liệu được xác định trước. Chúng ta sẽ tạo biểu đồ "Phát hiện hành vi gian lận" tài chính dựa trên các mẫu Biểu đồ Spanner.

Bật 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}

Tạo giản đồ cơ sở dữ liệu

Tạo một thực thể và cơ sở dữ liệu có các bảng cơ sở dữ liệu và biểu đồ thuộc tính. Lược đồ này theo dõi Tài khoản, Người và Giao dịch chuyển tiền giữa các tài khoản và người dùng.

LƯU Ý: Bạn có thể chạy các câu lệnh DDL này trong Spanner Studio. Vui lòng xem đường liên kết này để biết thông tin về cách tạo và truy vấn cơ sở dữ liệu Spanner từ bảng điều khiển 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)
  );

Điền sẵn dữ liệu

Chèn người

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');

Chèn tài khoản

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');

Liên kết người dùng với tài khoản

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');

Thêm dữ liệu chuyển

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');

3. Định cấu hình Gemini CLI và Spanner MCP

Phòng thí nghiệm này được thiết kế để sử dụng Gemini CLI làm tác nhân chính để thực hiện hầu hết các hành động và bước đầu tiên là định cấu hình tác nhân này để hoạt động với máy chủ MCP Spanner từ xa. Ngoài ra, bạn nên sử dụng phiên bản mới nhất của Gemini CLI và phiên bản mới nhất của Gemini, chẳng hạn như Gemini-3-pro hoặc Gemini-3-flash (hiện đang ở giai đoạn xem trước).

Nếu đã có phiên bản mới nhất của Gemini CLI và định cấu hình phiên bản này để sử dụng các mô hình Gemini mới nhất, thì bạn có thể bỏ qua 2 bước tiếp theo và chuyển thẳng đến bước 3.

Lấy khoá Gemini API

Để sử dụng các mô hình Gemini mới nhất trong Gemini CLI, bạn cần định cấu hình mô hình này bằng phương thức xác thực khoá API. Chúng ta có thể lấy khoá API trong Google AI Studio

Truy cập vào Google AI Studio -> Lấy khoá API trong trình duyệt.
Ở bên phải màn hình, hãy nhấp vào nút Create API key
Trong cửa sổ bật lên, hãy chọn dự án của bạn hoặc nhập nếu dự án đó không xuất hiện

Tạo khoá API.
Bạn có thể sao chép khoá bằng nút sao chép ở bên phải.

Khoá đã được chuẩn bị và giờ đây, chúng ta có thể dùng khoá này cho Gemini CLI

Định cấu hình Gemini CLI

Bạn có thể định cấu hình Gemini CLI thông qua tệp cấu hình chế độ cài đặt hoặc tương tác bằng lệnh /settings. Chúng ta muốn các chế độ cài đặt được lưu giữ trong tệp cài đặt.

Trước tiên, chúng ta sẽ tạo một thư mục cho dự án của mình. Hãy gọi thư mục projectspannermcp và chuyển sang thư mục đó bằng các lệnh sau.

mkdir ~/projectspannermcp
cd ~/projectspannermcp

Trong thư mục này, chúng ta sẽ tạo một thư mục cho các tệp cấu hình Gemini và sẽ chạy tất cả các lệnh. Theo mặc định, Gemini CLI sử dụng tệp cấu hình phạm vi người dùng và các tiện ích được cài đặt trong thư mục ~/.gemini. Nhưng chúng ta sẽ tạo cấu hình phạm vi dự án riêng trong thư mục ~/projectspannermcp. Hãy bắt đầu bằng cách tạo thư mục và tệp cấu hình.

mkdir ~/projectspannermcp/.gemini
touch ~/projectspannermcp/.gemini/settings.json

Sau đó, chúng ta mở tệp ~/projectspannermcp/.gemini/settings.json bằng trình chỉnh sửa Cloud Shell.

edit ~/projectspannermcp/.gemini/settings.json

Trong cửa sổ trình chỉnh sửa vừa mở, hãy thêm cấu hình sau.

{
  "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
    }
  }
}

Sau khi chỉnh sửa tệp, bạn có thể dùng ctrl+s để lưu các thay đổi và chuyển về thiết bị đầu cuối bằng cách nhấp vào nút Open Terminal

Tệp settings.json ở trên đặt loại xác thực Gemini CLI thành gemini-api-key và bạn cần cung cấp khoá cho mô hình. Bạn có thể thực hiện việc này bằng cách tạo một tệp .env trong thư mục mà bạn muốn làm việc với Gemini CLI và lưu khoá API để xác thực Gemini CLI dưới dạng một biến môi trường sẽ được chọn khi bạn khởi động IDE.

Hãy chỉnh sửa tệp bằng trình chỉnh sửa Cloud Shell

edit ~/projectspannermcp/.env

Và lưu trữ khoá API mà bạn đã tạo trong bước "Lấy khoá Gemini API" ở trên.

GEMINI_API_KEY= <YOUR_API_KEY>

Bây giờ, bạn có thể quay lại thiết bị đầu cuối và tiếp tục. Bước tiếp theo là cập nhật Gemini CLI lên phiên bản mới nhất. Phiên bản trong Google Cloud Shell hoặc trong môi trường của bạn có thể đã lỗi thời và có thể không hoạt động đúng cách với các cấu hình và dịch vụ MCP mới nhất. Vì vậy, bạn cần cập nhật Gemini CLI lên phiên bản mới nhất và khởi động phiên bản đó. Trong thiết bị đầu cuối, hãy thực thi lệnh sau.

cd ~/projectspannermcp/
npm install -g @google/gemini-cli@latest

Giờ đây, bạn có thể xác minh phiên bản. Xin lưu ý rằng nếu bạn đang làm việc trong Google Cloud Shell, thì mỗi lần bạn khởi động lại shell, shell có thể quay về phiên bản trước. Những thay đổi bạn thực hiện đối với chính Gemini CLI sẽ không được lưu vĩnh viễn trong Cloud Shell.

gemini --version

Thao tác này sẽ cho thấy phiên bản Gemini CLI mới nhất (phiên bản 0.27 tại thời điểm viết hướng dẫn này). Bạn có thể xác minh phiên bản mới nhất của Gemini CLI tại đây. Giờ đây, chúng ta có thể bắt đầu và đảm bảo rằng ứng dụng đang sử dụng mô hình Gemini mới nhất. Chạy lệnh sau trong thư mục dự án để khởi động Gemini CLI.

gemini

Khi Gemini CLI khởi động, bạn có thể kiểm tra phiên bản và mô hình bằng cách chạy lệnh /about trong giao diện. Bạn sẽ thấy nội dung tương tự như hình bên dưới.

Bạn có thể thấy rằng Gemini đang sử dụng mô hình Gemini-3 mới nhất. Các bước dưới đây minh hoạ việc truy vấn bằng ngôn ngữ tự nhiên và yêu cầu sử dụng mô hình Gemini-3.

Định cấu hình Gemini CLI để sử dụng MCP Spanner

Chúng tôi cần thêm một thông tin nữa vào tệp settings.json. Trước tiên, hãy thoát khỏi gemini cli (bạn có thể nhấn Ctrl+C hai lần).

Trong cùng settings.json như trên, chúng ta sẽ thêm đoạn mã để định cấu hình máy chủ MCP Spanner. Chúng tôi đã đưa toàn bộ nội dung của settings.json ở bên dưới. Lưu ý phần bắt đầu bằng "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"
   ]
 }
}

Trước khi tiếp tục sang bước tiếp theo, hãy xác thực

gcloud auth application-default login

Sau khi xác thực, hãy khởi động lại gemini-cli

gemini

4. Tạo mô hình đa phương thức, bao gồm cả các truy vấn tập trung vào biểu đồ

Hãy bắt đầu bằng cách liệt kê các phiên bản Spanner trong dự án mà bạn đã định cấu hình.

"Vui lòng liệt kê tất cả các phiên bản Spanner trong dự án <project1> của tôi (thay thế bằng mã dự án của bạn)"

Phản hồi:

The Spanner instances in your project are:
 [instance1]

"Vui lòng liệt kê tất cả cơ sở dữ liệu trong <instance1> (thay thế bằng phiên bản của bạn)"

Phản hồi:

The Spanner databases in [instance1] are:
  [database1]

Tiếp theo, hãy yêu cầu Gemini ghi nhớ phiên bản/cơ sở dữ liệu mà bạn đã chạy câu lệnh DDL và câu lệnh chèn trong phần thiết lập Spanner:

"Giả sử rằng tất cả các truy vấn đều được gửi đến db <your-db> trong phiên bản <your-instance> trừ phi có quy định khác"

NOTE: Vui lòng sử dụng phiên bản/cơ sở dữ liệu mà bạn đã chạy các câu lệnh DDL và câu lệnh chèn ở trên.

Sau khi kết nối, mô hình Gemini sẽ hiểu được giản đồ biểu đồ. Giờ đây, bạn có thể chạy các thao tác duyệt qua phức tạp bằng ngôn ngữ tự nhiên.

Mô hình sẽ tự động dịch những nội dung này sang GQL (Ngôn ngữ truy vấn đồ thị):

Xác định cấu trúc mạng

"Mô tả cấu trúc của biểu đồ thuộc tính "FinGraph". Nhãn nút và nhãn cạnh là gì?"

Phản hồi:

  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

Phát hiện hành vi gian lận và tham chiếu vòng

"Tìm mọi giao dịch chuyển tiền vòng tròn, trong đó tiền được gửi từ Tài khoản A và cuối cùng được trả lại Tài khoản A trong vòng 3 bước."

Phản hồi:

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.

Phân tích mối quan hệ chuyên sâu

"Xác định tất cả những Cá nhân sở hữu tài khoản đã gửi hơn 4.999.000 VND đến tài khoản của những Cá nhân khác trong vòng 24 tháng qua."

Phản hồi:

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).

Tìm đường

"Tìm đường đi ngắn nhất của các lượt chuyển giữa Tài khoản 16 và Tài khoản 20."

Phản hồi:

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.

5. Xin chúc mừng!

Chúc mừng bạn đã hoàn thành lớp học lập trình này.

Nội dung đã đề cập

Trong lớp học lập trình này, bạn đã tìm hiểu cách định cấu hình gemini-cli bằng máy chủ Spanner MCP và đưa ra các truy vấn bằng ngôn ngữ tự nhiên đối với dữ liệu Spanner Graph để hiển thị thông tin chi tiết. Sau đây là phần tóm tắt các mốc quan trọng:

Cơ sở hạ tầng được quản lý: Bật máy chủ MCP Spanner từ xa, giúp bạn không cần dùng các proxy cục bộ hoặc Hộp công cụ MCP.
Tích hợp biểu đồ: Đã định cấu hình Biểu đồ thuộc tính Spanner (FinGraph) với các Nút và Cạnh để biểu thị các mối quan hệ phức tạp.
Công cụ gốc: Kết nối Gemini CLI trực tiếp với điểm cuối Spanner được quản lý bằng cách sử dụng một lược đồ URI tiêu chuẩn.
SQL và GQL bằng ngôn ngữ tự nhiên: Thực hiện máy chủ bằng các câu lệnh cụ thể về biểu đồ, cho phép LLM thực hiện các thao tác duyệt nhiều bước và phát hiện chu kỳ mà không cần mã hoá SQL/GQL theo cách thủ công.
Sẵn sàng cho doanh nghiệp: Khám phá cách MCP được quản lý cung cấp một đường dẫn có thể mở rộng và được xác thực để các tác nhân AI tương tác với dữ liệu vận hành.