00-feature-store-intro.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "jirdTjhETQW0"
   },
   "source": [
    "# **redis-feast-gcp**: 00 - Feature Store Intro\n",
    "\n",
    "In this notebook, we will explore how a Feature Store works using Feast.\n",
    "\n",
    "**This notebook assumes that you've already set up your Feature Store in GCP using the `setup` instructions in the README.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![architecture](img/redis-feast-gcp-architecture.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "6cJFAJiuGxM3"
   },
   "source": [
    "## Fetching Historical Data\n",
    "\n",
    "The Feast SDK allows us to pull historical data to generate a training dataset. In this cae, the data comes from BigQuery tables, but unbeknownst to the user.\n",
    "\n",
    "To make things simpler, we use the [`DataFetcher`](utils/data_fetcher.py) class that wraps the Feast Python client."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Feast is an open source project that collects anonymized error reporting and usage statistics. To opt out or learn more see https://docs.feast.dev/reference/usage\n"
     ]
    }
   ],
   "source": [
    "from feature_store.repo import config\n",
    "from feature_store.utils import (\n",
    "    DataFetcher,\n",
    "    storage\n",
    ")\n",
    "\n",
    "# Load Feast feature store\n",
    "fs = storage.get_feature_store(\n",
    "    config_path=config.REPO_CONFIG,\n",
    "    bucket_name=config.BUCKET_NAME\n",
    ")\n",
    "\n",
    "# Load DataFetcher utility class\n",
    "data_fetcher = DataFetcher(fs)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['lag_1_vaccine_interest', 'lag_2_vaccine_interest', 'lag_1_vaccine_intent', 'lag_2_vaccine_intent', 'lag_1_vaccine_safety', 'lag_2_vaccine_safety', 'lag_1_weekly_vaccinations_count', 'lag_2_weekly_vaccinations_count']\n",
      "['weekly_vaccinations_count']\n"
     ]
    }
   ],
   "source": [
    "# The data fetcher class contains the list of input features to use for model training\n",
    "print(data_fetcher.X_cols)\n",
    "\n",
    "print(data_fetcher.y_col)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "colab": {
     "base_uri": "https://localhost:8080/",
     "height": 330
    },
    "id": "BqgiEP2Oz42q",
    "outputId": "40552317-644b-4ee6-d735-0ee5e48e79dd"
   },
   "outputs": [],
   "source": [
    "# Fetch historical training data with Feast\n",
    "ds = data_fetcher.get_training_data(\n",
    "    entity_query=f\"\"\"\n",
    "        select\n",
    "            state,\n",
    "            date as event_timestamp\n",
    "        from\n",
    "            {config.BIGQUERY_DATASET_NAME}.{config.WEEKLY_VACCINATIONS_TABLE}\n",
    "    \"\"\"\n",
    ")\n",
    "\n",
    "# Clean up any nulls\n",
    "ds.dropna(inplace=True)\n",
    "ds.sort_values(['event_timestamp', 'state'], axis=0, inplace=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Subset the data to the state of Virginia (in the US)\n",
    "virginia = ds[ds.state == 'Virginia']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>state</th>\n",
       "      <th>event_timestamp</th>\n",
       "      <th>lag_1_vaccine_interest</th>\n",
       "      <th>lag_2_vaccine_interest</th>\n",
       "      <th>lag_1_vaccine_intent</th>\n",
       "      <th>lag_2_vaccine_intent</th>\n",
       "      <th>lag_1_vaccine_safety</th>\n",
       "      <th>lag_2_vaccine_safety</th>\n",
       "      <th>lag_1_weekly_vaccinations_count</th>\n",
       "      <th>lag_2_weekly_vaccinations_count</th>\n",
       "      <th>weekly_vaccinations_count</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>3267</th>\n",
       "      <td>Virginia</td>\n",
       "      <td>2021-01-25 00:00:00+00:00</td>\n",
       "      <td>62.549712</td>\n",
       "      <td>64.178025</td>\n",
       "      <td>22.662099</td>\n",
       "      <td>25.802051</td>\n",
       "      <td>9.102064</td>\n",
       "      <td>8.580120</td>\n",
       "      <td>152933</td>\n",
       "      <td>115553.0</td>\n",
       "      <td>329892.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3331</th>\n",
       "      <td>Virginia</td>\n",
       "      <td>2021-02-01 00:00:00+00:00</td>\n",
       "      <td>59.771108</td>\n",
       "      <td>62.549712</td>\n",
       "      <td>23.881589</td>\n",
       "      <td>22.662099</td>\n",
       "      <td>9.060282</td>\n",
       "      <td>9.102064</td>\n",
       "      <td>329892</td>\n",
       "      <td>152933.0</td>\n",
       "      <td>278811.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3279</th>\n",
       "      <td>Virginia</td>\n",
       "      <td>2021-02-08 00:00:00+00:00</td>\n",
       "      <td>71.490393</td>\n",
       "      <td>59.771108</td>\n",
       "      <td>35.214495</td>\n",
       "      <td>23.881589</td>\n",
       "      <td>11.884993</td>\n",
       "      <td>9.060282</td>\n",
       "      <td>278811</td>\n",
       "      <td>329892.0</td>\n",
       "      <td>266744.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3251</th>\n",
       "      <td>Virginia</td>\n",
       "      <td>2021-02-15 00:00:00+00:00</td>\n",
       "      <td>67.818582</td>\n",
       "      <td>71.490393</td>\n",
       "      <td>34.463701</td>\n",
       "      <td>35.214495</td>\n",
       "      <td>12.675395</td>\n",
       "      <td>11.884993</td>\n",
       "      <td>266744</td>\n",
       "      <td>278811.0</td>\n",
       "      <td>318139.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3268</th>\n",
       "      <td>Virginia</td>\n",
       "      <td>2021-02-22 00:00:00+00:00</td>\n",
       "      <td>72.135382</td>\n",
       "      <td>67.818582</td>\n",
       "      <td>34.295162</td>\n",
       "      <td>34.463701</td>\n",
       "      <td>14.205749</td>\n",
       "      <td>12.675395</td>\n",
       "      <td>318139</td>\n",
       "      <td>266744.0</td>\n",
       "      <td>344859.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         state           event_timestamp  lag_1_vaccine_interest  \\\n",
       "3267  Virginia 2021-01-25 00:00:00+00:00               62.549712   \n",
       "3331  Virginia 2021-02-01 00:00:00+00:00               59.771108   \n",
       "3279  Virginia 2021-02-08 00:00:00+00:00               71.490393   \n",
       "3251  Virginia 2021-02-15 00:00:00+00:00               67.818582   \n",
       "3268  Virginia 2021-02-22 00:00:00+00:00               72.135382   \n",
       "\n",
       "      lag_2_vaccine_interest  lag_1_vaccine_intent  lag_2_vaccine_intent  \\\n",
       "3267               64.178025             22.662099             25.802051   \n",
       "3331               62.549712             23.881589             22.662099   \n",
       "3279               59.771108             35.214495             23.881589   \n",
       "3251               71.490393             34.463701             35.214495   \n",
       "3268               67.818582             34.295162             34.463701   \n",
       "\n",
       "      lag_1_vaccine_safety  lag_2_vaccine_safety  \\\n",
       "3267              9.102064              8.580120   \n",
       "3331              9.060282              9.102064   \n",
       "3279             11.884993              9.060282   \n",
       "3251             12.675395             11.884993   \n",
       "3268             14.205749             12.675395   \n",
       "\n",
       "      lag_1_weekly_vaccinations_count  lag_2_weekly_vaccinations_count  \\\n",
       "3267                           152933                         115553.0   \n",
       "3331                           329892                         152933.0   \n",
       "3279                           278811                         329892.0   \n",
       "3251                           266744                         278811.0   \n",
       "3268                           318139                         266744.0   \n",
       "\n",
       "      weekly_vaccinations_count  \n",
       "3267                   329892.0  \n",
       "3331                   278811.0  \n",
       "3279                   266744.0  \n",
       "3251                   318139.0  \n",
       "3268                   344859.0  "
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Inspect part of the dataset for Virginia\n",
    "virginia.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>state</th>\n",
       "      <th>event_timestamp</th>\n",
       "      <th>lag_1_vaccine_interest</th>\n",
       "      <th>lag_2_vaccine_interest</th>\n",
       "      <th>lag_1_vaccine_intent</th>\n",
       "      <th>lag_2_vaccine_intent</th>\n",
       "      <th>lag_1_vaccine_safety</th>\n",
       "      <th>lag_2_vaccine_safety</th>\n",
       "      <th>lag_1_weekly_vaccinations_count</th>\n",
       "      <th>lag_2_weekly_vaccinations_count</th>\n",
       "      <th>weekly_vaccinations_count</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>3304</th>\n",
       "      <td>Virginia</td>\n",
       "      <td>2023-01-02 00:00:00+00:00</td>\n",
       "      <td>10.72945</td>\n",
       "      <td>11.383411</td>\n",
       "      <td>1.831109</td>\n",
       "      <td>2.094199</td>\n",
       "      <td>1.352006</td>\n",
       "      <td>1.276527</td>\n",
       "      <td>46707</td>\n",
       "      <td>65773.0</td>\n",
       "      <td>46312.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3295</th>\n",
       "      <td>Virginia</td>\n",
       "      <td>2023-01-09 00:00:00+00:00</td>\n",
       "      <td>10.72945</td>\n",
       "      <td>11.383411</td>\n",
       "      <td>1.831109</td>\n",
       "      <td>2.094199</td>\n",
       "      <td>1.352006</td>\n",
       "      <td>1.276527</td>\n",
       "      <td>46312</td>\n",
       "      <td>46707.0</td>\n",
       "      <td>45059.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3242</th>\n",
       "      <td>Virginia</td>\n",
       "      <td>2023-01-16 00:00:00+00:00</td>\n",
       "      <td>10.72945</td>\n",
       "      <td>11.383411</td>\n",
       "      <td>1.831109</td>\n",
       "      <td>2.094199</td>\n",
       "      <td>1.352006</td>\n",
       "      <td>1.276527</td>\n",
       "      <td>45059</td>\n",
       "      <td>46312.0</td>\n",
       "      <td>37554.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3243</th>\n",
       "      <td>Virginia</td>\n",
       "      <td>2023-01-23 00:00:00+00:00</td>\n",
       "      <td>10.72945</td>\n",
       "      <td>11.383411</td>\n",
       "      <td>1.831109</td>\n",
       "      <td>2.094199</td>\n",
       "      <td>1.352006</td>\n",
       "      <td>1.276527</td>\n",
       "      <td>37554</td>\n",
       "      <td>45059.0</td>\n",
       "      <td>27998.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3339</th>\n",
       "      <td>Virginia</td>\n",
       "      <td>2023-01-30 00:00:00+00:00</td>\n",
       "      <td>10.72945</td>\n",
       "      <td>11.383411</td>\n",
       "      <td>1.831109</td>\n",
       "      <td>2.094199</td>\n",
       "      <td>1.352006</td>\n",
       "      <td>1.276527</td>\n",
       "      <td>27998</td>\n",
       "      <td>37554.0</td>\n",
       "      <td>6770.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         state           event_timestamp  lag_1_vaccine_interest  \\\n",
       "3304  Virginia 2023-01-02 00:00:00+00:00                10.72945   \n",
       "3295  Virginia 2023-01-09 00:00:00+00:00                10.72945   \n",
       "3242  Virginia 2023-01-16 00:00:00+00:00                10.72945   \n",
       "3243  Virginia 2023-01-23 00:00:00+00:00                10.72945   \n",
       "3339  Virginia 2023-01-30 00:00:00+00:00                10.72945   \n",
       "\n",
       "      lag_2_vaccine_interest  lag_1_vaccine_intent  lag_2_vaccine_intent  \\\n",
       "3304               11.383411              1.831109              2.094199   \n",
       "3295               11.383411              1.831109              2.094199   \n",
       "3242               11.383411              1.831109              2.094199   \n",
       "3243               11.383411              1.831109              2.094199   \n",
       "3339               11.383411              1.831109              2.094199   \n",
       "\n",
       "      lag_1_vaccine_safety  lag_2_vaccine_safety  \\\n",
       "3304              1.352006              1.276527   \n",
       "3295              1.352006              1.276527   \n",
       "3242              1.352006              1.276527   \n",
       "3243              1.352006              1.276527   \n",
       "3339              1.352006              1.276527   \n",
       "\n",
       "      lag_1_weekly_vaccinations_count  lag_2_weekly_vaccinations_count  \\\n",
       "3304                            46707                          65773.0   \n",
       "3295                            46312                          46707.0   \n",
       "3242                            45059                          46312.0   \n",
       "3243                            37554                          45059.0   \n",
       "3339                            27998                          37554.0   \n",
       "\n",
       "      weekly_vaccinations_count  \n",
       "3304                    46312.0  \n",
       "3295                    45059.0  \n",
       "3242                    37554.0  \n",
       "3243                    27998.0  \n",
       "3339                     6770.0  "
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "virginia.tail()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "count       106.000000\n",
       "mean     179285.452830\n",
       "std      148843.919624\n",
       "min        6770.000000\n",
       "25%       71501.500000\n",
       "50%      127141.000000\n",
       "75%      259355.250000\n",
       "max      644252.000000\n",
       "Name: weekly_vaccinations_count, dtype: float64"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "virginia.weekly_vaccinations_count.describe()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2023-02-06 15:34:18,297:          font_manager.py:1633              _load_fontmanager(): generated new fontManager\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<AxesSubplot: xlabel='lag_2_vaccine_interest', ylabel='weekly_vaccinations_count'>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAlYAAAGxCAYAAACgDPi4AAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjYuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8o6BhiAAAACXBIWXMAAA9hAAAPYQGoP6dpAABZPElEQVR4nO3de1hU5do/8O+ADILIGUHMAwapKCqKB7TIA1ty095aVkYWbrXaFh7RNMvjbhdmWZn1aqdXdGemlrlNTeNVwB0iKIqnlEBQTBkOKoyAAg7P74/9Y8XIaRgWzOn7ua65Lmc9z6y5YZnr7jncSyGEECAiIiKiFrMydABERERE5oKJFREREZFMmFgRERERyYSJFREREZFMmFgRERERyYSJFREREZFMmFgRERERyYSJFREREZFM2hk6AEtSXV2N69evo2PHjlAoFIYOh4iIiHQghMDt27fh7e0NK6vGx6SYWLWh69evo2vXroYOg4iIiPRw9epVPPDAA432YWLVhjp27AjgvxfG0dHRwNEQERGRLtRqNbp27SrdxxvDxKoN1Uz/OTo6MrEiIiIyMbos4+HidSIiIiKZMLEiIiIikgkTKyIiIiKZMLEiIiIikgkTKyIiIiKZMLEiIiIikgkTKyIiIiKZMLEiIiIikgkTKyIiIiKZMLEiIiIikgkfaUNEREQGk11Yiis3y9HDrQN83DsYOpwWY2JFREREba64vBJztqXjSGahdCzEzwPrIwLhZG9jwMhahlOBRERE1ObmbEtHUlaR1rGkrCLM3nbKQBHJg4kVERERtanswlIcySyERgit4xohcCSzEDlFZQaKrOWYWBEREVGbunKzvNH2yzeYWBERERHppLurfaPtPdxMdxE7EysiIiJqUz09HBDi5wFrhULruLVCgRA/D5PeHcjEioiIiNrc+ohAjPR11zo20tcd6yMCDRSRPFhugYiIiNqck70NtswYipyiMly+UcY6VkREREQt5eNuHglVDU4FEhEREcmEiRURERGRTJhYEREREcmEiRURERGRTJhYEREREcmEiRURERGRTJhYEREREcmEdayIiIio1WQXluLKzXKzKQDaFCZWREREJLvi8krM2ZaOI5mF0rEQPw+sjwiEk72NASNrXZwKJCIikkl2YSniMwqQU1Rm6FAMbs62dCRlFWkdS8oqwuxtpwwUUdvgiBUR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\n",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Investigate trends across features for prediction weekly vaccinations count!\n",
    "virginia.plot.scatter(y='weekly_vaccinations_count', x='lag_2_vaccine_interest')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Low latency feature retrieval\n",
    "\n",
    "To make a prediction in real-time, we need to do the following:\n",
    "\n",
    "1. Fetch our features from Redis using the Feast client\n",
    "2. Pass these features to our model\n",
    "3. Return these predictions to the user\n",
    "\n",
    "Here is an example pulling the latest features data from Redis (online store) for the state of *Virginia*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Fetch online feature\n",
    "online_feature = data_fetcher.get_online_data(state=\"Virginia\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>lag_1_vaccine_interest</th>\n",
       "      <th>lag_2_vaccine_interest</th>\n",
       "      <th>lag_1_vaccine_intent</th>\n",
       "      <th>lag_2_vaccine_intent</th>\n",
       "      <th>lag_1_vaccine_safety</th>\n",
       "      <th>lag_2_vaccine_safety</th>\n",
       "      <th>lag_1_weekly_vaccinations_count</th>\n",
       "      <th>lag_2_weekly_vaccinations_count</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>10.72945</td>\n",
       "      <td>11.383411</td>\n",
       "      <td>1.831109</td>\n",
       "      <td>2.094199</td>\n",
       "      <td>1.352006</td>\n",
       "      <td>1.276527</td>\n",
       "      <td>6770</td>\n",
       "      <td>27998</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   lag_1_vaccine_interest  lag_2_vaccine_interest  lag_1_vaccine_intent  \\\n",
       "0                10.72945               11.383411              1.831109   \n",
       "\n",
       "   lag_2_vaccine_intent  lag_1_vaccine_safety  lag_2_vaccine_safety  \\\n",
       "0              2.094199              1.352006              1.276527   \n",
       "\n",
       "   lag_1_weekly_vaccinations_count  lag_2_weekly_vaccinations_count  \n",
       "0                             6770                            27998  "
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "online_feature"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Alternatives for Feature Retrieval\n",
    "- Instead of using the Feast SDK (and our Data Fetcher class), you can also setup and use the [Python feature server](https://docs.feast.dev/reference/feature-servers/python-feature-server).\n",
    "- If you need the best in class performance for feature retrieval and don't mind the extra setup, Feast also supports a [Go feature server](https://docs.feast.dev/reference/feature-servers/go-feature-server) that is much faster than standard Python.\n",
    "\n",
    "If included in the project, you can run these HTTP (or gRPC) servers with `feast serve` command. The doc links above show how to set that up."
   ]
  }
 ],
 "metadata": {
  "colab": {
   "collapsed_sections": [],
   "name": "Fraud Detection Tutorial",
   "provenance": [],
   "toc_visible": true
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.13"
  },
  "vscode": {
   "interpreter": {
    "hash": "e1c5a7c9cc0d58080444e081b74a0823c09a12f0209aca730c38726ea6940124"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}