BigQuery RAG MCP Server

Частный сервис Model Context Protocol (MCP), который преобразует вопрос на естественном языке в эмбеддинг, выполняет семантический поиск по фрагментам документов, хранящимся в BigQuery, и возвращает структурированные отрывки с метаданными источника и страницы.

Этот репозиторий владеет уровнем поиска более крупного чат-бота, основанного на документах. Репозиторий сопутствующего приложения владеет оркестрацией Google ADK, генерацией ответов Gemini, аутентификацией Firebase, API /chat и интерфейсом React.

Сопутствующее приложение: shrprabh/atomic-habits-adk-rag

Развертывание в реальном времени

URL сервиса намеренно не является общедоступным в браузере. Вызывающий должен иметь роль roles/run.invoker на сервисе и отправлять подписанный Google токен идентификации, аудиторией которого является базовый URL MCP.

Сквозная архитектура

React application on Firebase Hosting
        │ Firebase ID token
        ▼
ADK Agent API on Cloud Run
        │ Google service identity token
        ▼
Private MCP service on Cloud Run  ◀── this repository
        │ parameterized BigQuery SQL
        ▼
AI.GENERATE_EMBEDDING
        │ 1,536-dimensional query vector
        ▼
BigQuery VECTOR_SEARCH (COSINE)
        │
        ▼
Top document passages + page metadata

Что делает этот сервис

• Предоставляет инструмент MCP только для чтения с именем semantic_search.

• Проверяет query и top_k с помощью схем MCP, сгенерированных Pydantic.

• Создает эмбеддинг запроса с помощью AI.GENERATE_EMBEDDING, используя RETRIEVAL_QUERY.

• Выполняет VECTOR_SEARCH по косинусному расстоянию для сохраненных эмбеддингов документов.

• Использует параметризованное значение запроса вместо вставки пользовательского ввода в SQL.

• Возвращает структурированные поля источника, страницы, главы, раздела, расстояния и схожести.

• Работает как stateless Streamable HTTP MCP сервер.

• Сохраняет сервис поиска частным с помощью Cloud Run IAM.

• Не вызывает Gemini для составления ответа; генерация принадлежит сопутствующему сервису ADK.

Ресурсы BigQuery, используемые этим проектом

Текущая таблица мала, поэтому в этой реализации намеренно используется полный перебор векторов. Векторный индекс становится полезным после того, как корпус вырастет достаточно, чтобы оправдать приближенный поиск ближайших соседей и обслуживание индекса.

Контракт инструмента MCP

semantic_search

Входные данные:

{
  "query": "What is the two-minute rule?",
  "top_k": 5
}

Проверка:

Упрощенный вывод:

{
  "query": "What is the two-minute rule?",
  "result_count": 5,
  "results": [
    {
      "chunk_id": 480,
      "document_id": "atomic_habits",
      "content": "Retrieved passage text...",
      "title": "Atomic Habits",
      "author": "James Clear",
      "source": "atomic-habits.pdf",
      "page_start": 96,
      "page_end": 96,
      "chapter": "...",
      "section": "...",
      "distance": 0.18,
      "similarity": 0.82
    }
  ]
}

Структура репозитория

bigquery-rag-mcp/
├── server.py                 # MCP tool, BigQuery query, health route
├── test_mcp.py               # In-process MCP regression test
├── test_deployed_mcp.py      # Authenticated test against Cloud Run
├── rag_client.py             # Local in-process RAG reference client
├── requirements.txt
├── Dockerfile
├── .env.example
└── .gitignore

rag_client.py импортирует mcp из server.py, поэтому он выполняет инструмент в том же процессе Python. Он полезен как локальный эталонный или регрессионный клиент, но не является частью развернутого производственного пути запроса. Сопутствующее приложение ADK вызывает этот сервис удаленно через /mcp.

Предварительные требования

• Python 3.12+

• Google Cloud CLI

• Проект Google Cloud с включенным биллингом

• API BigQuery, BigQuery Connection, Vertex AI, Cloud Run, Cloud Build и Artifact Registry

• Существующий набор данных BigQuery, модель эмбеддинга и таблица эмбеддингов, соответствующие настроенной схеме

• Разрешение на создание сервисных аккаунтов и управление IAM для Cloud Run и BigQuery

1. Клонирование и установка

git clone https://github.com/shrprabh/bigquery-rag-mcp.git
cd bigquery-rag-mcp

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
pip install -r requirements.txt

Для локальной разработки вне Cloud Shell:

gcloud auth login
gcloud auth application-default login
gcloud config set project bigquery-semantic-search

Никогда не коммитьте учетные данные приложения по умолчанию или файлы ключей сервисного аккаунта.

2. Настройка окружения

cp .env.example .env

Ожидаемые значения:

GOOGLE_CLOUD_PROJECT=bigquery-semantic-search
BQ_DATASET=atomic_habits_rag
BQ_LOCATION=us-central1
EMBEDDING_DIM=1536

server.py читает эти значения из окружения процесса. Зафиксированный .env.example является только документацией; используйте явные экспорты локально или переменные окружения Cloud Run при развертывании.

3. Проверка ресурсов BigQuery

Выполните в редакторе BigQuery:

SELECT
  ARRAY_LENGTH(embedding) AS dimensions,
  COUNT(*) AS row_count
FROM `bigquery-semantic-search.atomic_habits_rag.article_embeddings`
GROUP BY dimensions;

Ожидаемое для текущего набора данных:

dimensions  row_count
1536        1222

Подтвердите, что модель существует:

SELECT
  model_name,
  model_type
FROM `bigquery-semantic-search.atomic_habits_rag.INFORMATION_SCHEMA.MODELS`
WHERE model_name = 'embedding_model';

4. Настройка IAM времени выполнения

Установите переменные:

export PROJECT_ID="bigquery-semantic-search"
export REGION="us-central1"
export CONNECTION_ID="vertex_ai_connection"
export MCP_SERVICE="bigquery-rag-mcp"
export MCP_SA_NAME="bigquery-rag-mcp-sa"
export MCP_SA="${MCP_SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud config set project "$PROJECT_ID"

Включите API:

gcloud services enable \
  bigquery.googleapis.com \
  bigqueryconnection.googleapis.com \
  aiplatform.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  --project="$PROJECT_ID"

Создайте сервисный аккаунт времени выполнения, если он еще не существует:

gcloud iam service-accounts describe "$MCP_SA" \
  --project="$PROJECT_ID" >/dev/null 2>&1 || \
gcloud iam service-accounts create "$MCP_SA_NAME" \
  --project="$PROJECT_ID" \
  --display-name="BigQuery RAG MCP Server"

Предоставьте сервисному аккаунту разрешение на выполнение запросов и чтение набора данных/модели:

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${MCP_SA}" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${MCP_SA}" \
  --role="roles/bigquery.dataViewer"

Необходимое разрешение на подключение

Поскольку AI.GENERATE_EMBEDDING использует подключение к облачным ресурсам BigQuery, идентификатор времени выполнения MCP также должен иметь разрешение на использование vertex_ai_connection.

В консоли Google Cloud:

1. Откройте BigQuery → ваш проект → Connections.

2. Выберите vertex_ai_connection в us-central1.

3. Выберите Share.

4. Добавьте bigquery-rag-mcp-sa@bigquery-semantic-search.iam.gserviceaccount.com.

5. Предоставьте роль BigQuery Connection User (roles/bigquery.connectionUser).

Не используйте bq add-iam-policy-binding --connection_type=...; этот флаг не предоставляет общий доступ к подключению и отклоняется текущими версиями bq. Для предоставления общего доступа на уровне подключения следует использовать консоль Cloud или API BigQuery Connections.

Само подключение имеет управляемый Google сервисный аккаунт. Этот сервисный аккаунт подключения должен иметь соответствующую роль пользователя Vertex AI/Agent Platform в проекте, чтобы удаленная модель эмбеддинга могла вызывать свою конечную точку.

Без этих разрешений на подключение в журнале MCP будет ошибка, похожая на:

403 Access Denied: User does not have bigquery.connections.use permission

5. Локальное тестирование

Скомпилируйте файлы:

python -m py_compile server.py test_mcp.py rag_client.py

Запустите прямой регрессионный тест MCP:

python test_mcp.py

Запустите HTTP-сервер:

python server.py

Конечные точки:

http://localhost:8000/health
http://localhost:8000/mcp

Из другого терминала:

curl http://localhost:8000/health

Ожидается:

{"status":"healthy"}

При желании запустите локальный эталонный клиент генерации с обоснованием:

python rag_client.py

6. Развертывание частного сервиса MCP

gcloud run deploy "$MCP_SERVICE" \
  --source=. \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --service-account="$MCP_SA" \
  --no-allow-unauthenticated \
  --memory="1Gi" \
  --timeout="300" \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,BQ_DATASET=atomic_habits_rag,BQ_LOCATION=$REGION,EMBEDDING_DIM=1536"

Cloud Run предоставляет PORT; server.py привязывается к 0.0.0.0 и использует этот порт.

Получите канонический URL сервиса:

export MCP_URL="$(
  gcloud run services describe "$MCP_SERVICE" \
    --project="$PROJECT_ID" \
    --region="$REGION" \
    --format='value(status.url)'
)"

echo "$MCP_URL"

Проверьте аутентифицированный маршрут здоровья:

curl -i \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  "$MCP_URL/health"

Ожидается: HTTP 200 и {"status":"healthy"}.

7. Тестирование развернутого инструмента MCP

export MCP_URL="https://bigquery-rag-mcp-nfp4nl2vna-uc.a.run.app"
python test_deployed_mcp.py

Запрос:

What is the two-minute rule?

Тестовый клиент должен инициализировать сессию MCP, вызвать semantic_search и вывести структурированные результаты поиска. Одного успешного HTTP-статуса недостаточно; убедитесь, что result_count больше нуля и результат содержит метаданные страницы.

8. Авторизация сопутствующего сервиса ADK

После создания сервисного аккаунта агента в сопутствующем репозитории разрешите ему вызывать этот частный сервис:

export AGENT_SA="bigquery-rag-agent-sa@bigquery-semantic-search.iam.gserviceaccount.com"

gcloud run services add-iam-policy-binding "$MCP_SERVICE" \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --member="serviceAccount:${AGENT_SA}" \
  --role="roles/run.invoker"

Проверьте:

gcloud run services get-iam-policy "$MCP_SERVICE" \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:${AGENT_SA}" \
  --format="table(bindings.role,bindings.members)"

Сервисному аккаунту ADK нужна роль run.invoker на этом сервисе. Ему не нужны роли BigQuery сервиса MCP, потому что каждый сервис Cloud Run имеет свою собственную идентичность и ответственность.

Продолжите с руководством по развертыванию ADK + React.

Наблюдаемость

Чтение последних журналов:

gcloud run services logs read "$MCP_SERVICE" \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --limit=100

Полезное сообщение об успешном выполнении:

Running semantic search with top_k=5

Метрики Cloud Run доступны по адресу:

Google Cloud Console → Cloud Run → bigquery-rag-mcp → Metrics

История запросов BigQuery и обработанные байты доступны в истории заданий BigQuery или INFORMATION_SCHEMA.JOBS_BY_PROJECT.

Устранение неполадок

Безопасность и обработка данных

• Сервис Cloud Run MCP остается частным.

• Ключи JSON сервисных аккаунтов не развертываются и не коммитятся.

• Используются идентичность сервиса Cloud Run и кратковременные ID-токены Google.

• Текст пользовательского запроса передается в BigQuery как параметр.

• Инструмент помечен как только для чтения и возвращает только доказательства поиска.

• .env, файлы ADC, PDF, фрагменты JSONL, журналы и локальные базы данных игнорируются Git.

• Исходный документ и извлеченные фрагменты не распространяются в этом репозитории.

• Не раскрывайте токены аутентификации в скриншотах или журналах.

Текущие ограничения

• Корпус содержит 1 222 фрагмента из одного документа.

• Поиск выполняется полным перебором и не имеет векторного индекса.

• Пока нет реранкера или набора для оценки поиска.

• Инструмент MCP возвращает отрывки; качество ответа и цитирование зависят от сопутствующего агента.

• Текущая реализация портфолио является специфичной для документа, а не многопользовательской платформой для приема данных.

Рекомендуемые дальнейшие улучшения

1. Добавить оценку поиска с набором вопросов/ожидаемых источников.

2. Добавить пороги схожести и тесты на воздержание.

3. Поддержать прием документов и проверку метаданных как отдельный конвейер.

4. Добавить фильтры арендатора/документа перед поиском.

5. Добавить векторный индекс после того, как набор данных станет достаточно большим.

6. Добавить структурированные поля Cloud Logging для задержки и количества результатов без записи содержимого отрывков.

7. Добавить модульные тесты, имитирующие BigQuery, и интеграционные тесты для развернутого сервиса MCP.

Публикация на GitHub

git add README.md
git commit -m "Add end-to-end MCP deployment documentation"

git remote add origin https://github.com/shrprabh/bigquery-rag-mcp.git
git push -u origin main

Если origin уже существует, не добавляйте его снова. Проверьте с помощью git remote -v, затем выполните только git push.

Официальные ссылки

• MCP Python SDK

• BigQuery AI.GENERATE_EMBEDDING

• BigQuery vector search

• BigQuery connection access

• Cloud Run service-to-service authentication

• Cloud Run service identity

Автор

Шрейас Прабхакар

• GitHub: @shrprabh

• LinkedIn: linkedin.com/in/shreyasprabhakar

• Medium: @pshreyasgowda1997