1. Обзор
В этом практическом занятии демонстрируется, как выполнять запросы к графу в Spanner с помощью gemini-cli и серверов протокола контекста модели (MCP) от Google. Интегрируя многомодельную базу данных Spanner, включая Spanner Graph, с управляемым сервисом MCP, вы можете использовать естественный язык для выявления скрытых взаимосвязей в ваших данных — таких как круги мошенничества или зависимости в цепочке поставок — в одной базе данных без необходимости вручную писать сложные запросы GQL (Graph Query Language) или SQL.
Что вы узнаете
- Как настроить многомодельную базу данных Spanner, включая Spanner Graph для MCP.
- Как подключить интерфейс командной строки Gemini к управляемой удаленной конечной точке сервиса Spanner.
- Как использовать естественный язык для автоматической генерации SQL-запросов, интегрированных с GQL, для выполнения обхода графов и сопоставления с шаблонами, а также операций с реляционными базами данных.
- Рекомендации по обеспечению безопасности графовых данных в рабочих процессах искусственного интеллекта.
Предварительные требования
- Проект в Google Cloud с включенной функцией выставления счетов.
- Доступ к терминалу (например, Cloud Shell). См. этот практический пример.
- Интерфейс командной строки
gcloudустановлен и авторизован. - Доступ к Gemini CLI .
ПРИМЕЧАНИЕ: Все команды необходимо выполнять в терминале Unix. Для получения доступа к терминалу с правами доступа к gcloud и соответствующей аутентификацией, пожалуйста, ознакомьтесь с указанными выше предварительными требованиями.
2. Настройка многомодельной среды Spanner.
Управляемая MCP работает лучше всего, когда схема базы данных предварительно определена. Мы создадим финансовый граф «Обнаружения мошенничества» на основе примеров Spanner Graph.
Включить 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');
3. Настройте Gemini CLI и Spanner MCP.
Лабораторная работа разработана с использованием Gemini CLI в качестве основного агента для выполнения большинства действий, и первым шагом является его настройка для работы с удаленным сервером Spanner MCP. Также настоятельно рекомендуется использовать последнюю версию Gemini CLI и последнюю версию Gemini, например Gemini-3-pro или Gemini-3-flash (в настоящее время находится в режиме предварительного просмотра).
Если у вас уже установлена последняя версия Gemini CLI и вы настроили её для работы с последними моделями Gemini, то можете пропустить следующие 2 шага и сразу перейти к шагу 3.
Получить ключ API Gemini
Для использования новейших моделей Gemini в Gemini CLI необходимо настроить аутентификацию с помощью ключа API. Ключ API можно получить в Google AI Studio.
- Перейдите в Google AI Studio -> Получить ключ API в вашем браузере.
- В правой части экрана нажмите кнопку
Create API key - Во всплывающем окне выберите свой проект или импортируйте его, если он там не отображается.
- Создайте ключ API.
- Вы можете скопировать ключ, используя кнопку копирования справа.
Ключ подготовлен, и теперь мы можем использовать его для Gemini CLI.
Настройка Gemini CLI
Gemini CLI можно настроить через файл конфигурации настроек или в интерактивном режиме с помощью команды /settings . Нам нужно, чтобы наши настройки сохранялись в файле настроек.
Сначала создадим директорию для нашего проекта. Назовём её projectspannermcp и перейдём в неё с помощью следующих команд.
mkdir ~/projectspannermcp
cd ~/projectspannermcp
В этой директории мы создадим каталог для конфигурационных файлов Gemini и будем выполнять все наши команды. Gemini CLI по умолчанию использует конфигурационный файл пользовательской области видимости и расширения, установленные в директории ~/.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, то при каждом перезапуске оболочки она может возвращаться к предыдущей версии. Изменения, внесенные вами в саму CLI Gemini, не являются постоянными в Cloud Shell.
gemini --version
Должна отображаться последняя версия Gemini CLI (версия 0.27 на момент написания лабораторной работы). Проверить последнюю версию Gemini CLI можно здесь . Теперь мы можем запустить его и убедиться, что он использует последнюю модель Gemini. Выполните следующую команду в папке вашего проекта, чтобы запустить Gemini CLI.
gemini
После запуска Gemini CLI вы можете проверить версию и модель, выполнив команду /about в интерфейсе. Вы должны увидеть что-то похожее на изображение ниже.
Как видите, используется новейшая модель Gemini-3. Для выполнения описанных ниже шагов, демонстрирующих обработку запросов на естественном языке, требуется использование модели Gemini-3.
Настройте Gemini CLI для использования 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
4. Генерация мультимодельных запросов, включая запросы, ориентированные на графы.
Начнём с перечисления экземпляров Spanner в вашем настроенном проекте.
"Пожалуйста, перечислите все экземпляры Spanner в моем проекте <project1> (замените на идентификатор вашего проекта)"
Ответ:
The Spanner instances in your project are:
[instance1]
"Пожалуйста, перечислите все базы данных в <instance1> (замените на ваш экземпляр)"
Ответ:
The Spanner databases in [instance1] are:
[database1]
Далее, давайте укажем gemini запомнить экземпляр/базу данных, где вы выполняли операторы DDL и операторы вставки в разделе настройки Spanner:
«Предполагается, что все запросы должны отправляться в базу данных <ваша-база данных> в экземпляре <ваш-экземпляр>, если не указано иное».
ПРИМЕЧАНИЕ : Пожалуйста, используйте тот же экземпляр/базу данных, для которой вы выполняли операторы DDL и операторы вставки, указанные выше .
После установления соединения модель Gemini понимает схему графа. Теперь вы можете выполнять сложные обходы графа, используя естественный язык.
Модель автоматически преобразует эти данные в GQL (Graph Query Language):
Определение сетевых структур
«Опишите структуру графа свойств '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
Выявление мошенничества и циклов
«Найдите все циклические переводы, в которых деньги были отправлены со счета А и в конечном итоге возвращены на счет А в пределах 3 переходов».
Ответ:
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.
Глубокий анализ взаимоотношений
«Выявите всех лиц, владеющих счетами, с которых за последние 24 месяца было переведено более 499 долларов США на счета, принадлежащие разным лицам».
Ответ:
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).
Поиск пути
"Найдите кратчайший путь переводов между счетом с идентификатором 16 и счетом с идентификатором 20."
Ответ:
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. Поздравляем!
Поздравляем с завершением практического занятия!
Что мы рассмотрели
В этом практическом занятии вы научились настраивать gemini-cli с сервером Spanner MCP и выполнять запросы на естественном языке к вашим данным Spanner Graph для получения ценных аналитических выводов. Вот краткое изложение основных этапов:
- Управляемая инфраструктура: Включен удаленный сервер Spanner MCP, что устраняет необходимость в локальных прокси-серверах или MCP Toolbox.
- Интеграция с графами: Настроен граф свойств Spanner (FinGraph) с узлами и ребрами для представления сложных взаимосвязей.
- Встроенные инструменты: Подключение интерфейса командной строки Gemini к управляемой конечной точке Spanner выполнено напрямую с использованием стандартной схемы URI.
- SQL и GQL на естественном языке: Сервер был протестирован с помощью запросов, специфичных для графа, что позволило LLM выполнять многошаговые обходы и обнаружение циклов без ручного написания кода на SQL/GQL.
- Готовность предприятия: рассмотрено, как управляемый MCP обеспечивает масштабируемый, аутентифицированный путь для взаимодействия агентов ИИ с оперативными данными.