From 830ca0930623761dd04b395f83308c788b3578b6 Mon Sep 17 00:00:00 2001
From: jaivaldesai <151085170+jaivaldesai@users.noreply.github.com>
Date: Mon, 7 Oct 2024 09:52:49 -0700
Subject: [PATCH 1/2] Updating helper function for processing tables
---
parsing_and_chunking_with_BYO.ipynb | 1388 +++++++++++++++++++++++++++
1 file changed, 1388 insertions(+)
create mode 100644 parsing_and_chunking_with_BYO.ipynb
diff --git a/parsing_and_chunking_with_BYO.ipynb b/parsing_and_chunking_with_BYO.ipynb
new file mode 100644
index 00000000..d8ac9959
--- /dev/null
+++ b/parsing_and_chunking_with_BYO.ipynb
@@ -0,0 +1,1388 @@
+{
+ "cells": [
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "DuN2KIZUlzbS"
+ },
+ "outputs": [],
+ "source": [
+ "# Copyright 2024 Google LLC\n",
+ "#\n",
+ "# Licensed under the Apache License, Version 2.0 (the \"License\");\n",
+ "# you may not use this file except in compliance with the License.\n",
+ "# You may obtain a copy of the License at\n",
+ "#\n",
+ "# https://www.apache.org/licenses/LICENSE-2.0\n",
+ "#\n",
+ "# Unless required by applicable law or agreed to in writing, software\n",
+ "# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
+ "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
+ "# See the License for the specific language governing permissions and\n",
+ "# limitations under the License."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "q3pW20ECIDpX"
+ },
+ "source": [
+ "# Parsing and Chunking in Vertex AI Search: Featuring BYO Capabilities\n",
+ "\n",
+ " \n",
+ " \n",
+ " ![\"Google](\"https://cloud.google.com/ml-engine/images/colab-logo-32px.png\")
Open in Colab\n",
+ " \n",
+ " | \n",
+ " \n",
+ " \n",
+ " ![\"Google](\"https://lh3.googleusercontent.com/JmcxdQi-qOpctIvWKgPtrzZdJJK-J3sWE1RsfjZNwshCFgE_9fULcNpuXYTilIR2hjwN\")
Open in Colab Enterprise\n",
+ " \n",
+ " | \n",
+ " \n",
+ " \n",
+ " ![\"Vertex](\"https://lh3.googleusercontent.com/UiNooY4LUgW_oTvpsNhPpQzsstV5W8F7rYgxgGBD85cWJoLmrOzhVs_ksK_vgx40SHs7jCqkTkCk=e14-rj-sc0xffffff-h130-w32\")
Open in Workbench\n",
+ " \n",
+ " | \n",
+ " \n",
+ " \n",
+ " ![\"GitHub](\"https://cloud.google.com/ml-engine/images/github-logo-32px.png\")
View on GitHub\n",
+ " \n",
+ " | \n",
+ "
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "YQpT9IS3K-Fn"
+ },
+ "source": [
+ "| | |\n",
+ "|----------|-------------|\n",
+ "| Author(s) | Jaival Desai, Hossein Mansour|\n",
+ "| Reviewers(s) | Allie Chen, Rajesh Thallam|\n",
+ "| Last updated | 2024-08-08: The first draft |"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "zNu-9XmEDF52"
+ },
+ "source": [
+ "# Overview\n",
+ "\n",
+ "In this notebook, we will demonstrate how to retrieve Parsed and Chunked documents from a [Vertex AI Search](https://cloud.google.com/generative-ai-app-builder/docs/introduction) (VAIS) datastore. Additionally, we will show how to Bring Your Own Chunks (BYOC) and ingest them into the datastore as needed. You can find more information [here](https://cloud.google.com/generative-ai-app-builder/docs/parse-chunk-documents#bring-parsed-document).\n",
+ "\n",
+ "We will perform the following steps:\n",
+ "\n",
+ "- [Prerequisite] Create a VAIS Datastore and import sample documents\n",
+ "- Get [Processed Document](https://cloud.google.com/generative-ai-app-builder/docs/parse-chunk-documents#get-parsed-documents) from datastore\n",
+ "- Get [Chunks](https://cloud.google.com/generative-ai-app-builder/docs/parse-chunk-documents#get-processed-chunks) from datastore\n",
+ "- Reconstruct the document from Chunks for visual inspection\n",
+ "- Store Chunks for offline review and/or edit\n",
+ "-[Bring your Own Chunks](https://cloud.google.com/generative-ai-app-builder/docs/parse-chunk-documents#bring-chunks). At the time of publishing this notebook, the BYOC feature is available under private preview. To be allowlisted for this feature, please contact your Google account team.\n",
+ "\n",
+ "\n",
+ "\n",
+ "REST API is used throughout this notebook. Please consult the [official documentation](https://cloud.google.com/generative-ai-app-builder/docs/apis) for alternative ways to achieve the same goal, namely Client libraries and RPC.\n",
+ "\n",
+ "\n",
+ "# Vertex AI Search\n",
+ "Vertex AI Search (VAIS) is a fully-managed platform, powered by large language models, that lets you build AI-enabled search and recommendation experiences for your public or private websites or mobile applications\n",
+ "\n",
+ "VAIS can handle a diverse set of data sources including structured, unstructured, and website data, as well as data from third-party applications such as Jira, Salesforce, and Confluence.\n",
+ "\n",
+ "VAIS also has built-in integration with LLMs which enables you to provide answers to complex questions, grounded in your data\n",
+ "\n",
+ "#Using this Notebook\n",
+ "If you're running outside of Colab, depending on your environment you may need to install pip packages that are included in the Colab environment by default but are not part of the Python Standard Library. Outside of Colab you'll also notice comments in code cells that look like #@something, these trigger special Colab functionality but don't change the behavior of the notebook.\n",
+ "\n",
+ "This tutorial uses the following Google Cloud services and resources:\n",
+ "\n",
+ "- Service Usage API\n",
+ "- Discovery Engine\n",
+ "- Google Cloud Storage Client\n",
+ "\n",
+ "This notebook has been tested in the following environment:\n",
+ "\n",
+ "- Python version = 3.10.12\n",
+ "- google.cloud.storage = 2.8.0\n",
+ "- google.auth = 2.27.0\n",
+ "\n",
+ "# Getting Started\n",
+ "\n",
+ "The following steps are necessary to run this notebook, no matter what notebook environment you're using.\n",
+ "\n",
+ "If you're entirely new to Google Cloud, [get started here](https://cloud.google.com/docs/get-started)\n",
+ "\n",
+ "## Google Cloud Project Setup\n",
+ "\n",
+ "1. [Select or create a Google Cloud project](https://console.cloud.google.com/cloud-resource-manager). When you first create an account, you get a $300 free credit towards your compute/storage costs\n",
+ "2. [Make sure that billing is enabled for your project](https://cloud.google.com/billing/docs/how-to/modify-project)\n",
+ "3. [Enable the Service Usage API](https://console.cloud.google.com/apis/library/serviceusage.googleapis.com)\n",
+ "4. [Enable the Cloud Storage API](https://console.cloud.google.com/flows/enableapi?apiid=storage.googleapis.com)\n",
+ "5. [Enable the Discovery Engine API for your project](https://console.cloud.google.com/marketplace/product/google/discoveryengine.googleapis.com)\n",
+ "\n",
+ "## Google Cloud Permissions\n",
+ "\n",
+ "Ideally you should have [Owner role](https://cloud.google.com/iam/docs/understanding-roles) for your project to run this notebook. If that is not an option, you need at least the following [roles](https://cloud.google.com/iam/docs/granting-changing-revoking-access)\n",
+ "- **`roles/serviceusage.serviceUsageAdmin`** to enable APIs\n",
+ "- **`roles/iam.serviceAccountAdmin`** to modify service agent permissions\n",
+ "- **`roles/discoveryengine.admin`** to modify discoveryengine assets\n",
+ "- **`roles/storage.objectAdmin`** to modify and delete GCS buckets"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "JwTJMRNlrOEf"
+ },
+ "source": [
+ "#Setup Environment"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "lJFp9LUmrSOf"
+ },
+ "source": [
+ "## Authentication\n",
+ "\n",
+ " If you're using Colab, run the code in the next cell. Follow the popups and authenticate with an account that has access to your Google Cloud [project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects).\n",
+ "\n",
+ "If you're running this notebook somewhere besides Colab, make sure your environment has the right Google Cloud access. If that's a new concept to you, consider looking into [Application Default Credentials for your local environment](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev) and [initializing the Google Cloud CLI](https://cloud.google.com/docs/authentication/gcloud). In many cases, running `gcloud auth application-default login` in a shell on the machine running the notebook kernel is sufficient.\n",
+ "\n",
+ "More authentication options are discussed [here](https://cloud.google.com/docs/authentication)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "-OKbRWQGrc-R"
+ },
+ "outputs": [],
+ "source": [
+ "# Colab authentication.\n",
+ "import sys\n",
+ "\n",
+ "if \"google.colab\" in sys.modules:\n",
+ " from google.colab import auth\n",
+ "\n",
+ " auth.authenticate_user()\n",
+ " print(\"Authenticated\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "pqF-4eiwP_j8"
+ },
+ "outputs": [],
+ "source": [
+ "from google.auth import default\n",
+ "from google.auth.transport.requests import AuthorizedSession\n",
+ "\n",
+ "creds, _ = default()\n",
+ "authed_session = AuthorizedSession(creds)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "kdQPp72R11pd"
+ },
+ "source": [
+ "## Import Libraries"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "JeAqU1WBrXDy"
+ },
+ "outputs": [],
+ "source": [
+ "import sys\n",
+ "import time\n",
+ "import os\n",
+ "import json\n",
+ "import glob\n",
+ "import re\n",
+ "import textwrap\n",
+ "import subprocess\n",
+ "from typing import Dict, Any, List, Tuple\n",
+ "from urllib.parse import urlparse\n",
+ "from io import BytesIO\n",
+ "\n",
+ "import requests\n",
+ "import pandas as pd\n",
+ "from google.cloud import storage\n",
+ "from google.auth import default\n",
+ "from google.auth.transport.requests import AuthorizedSession"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "MGXEinm3q1ks"
+ },
+ "source": [
+ "## Configure environment\n",
+ "\n",
+ "You can enter the ID for an existing Vertex AI Search App and Datastore to be used in this notebook.\n",
+ "\n",
+ "Alternatively, you can enter the desired IDs for non-existings App and Datastore and they will be created later in this notebook.\n",
+ "\n",
+ "Same applies to the Cloud Storage buckets to store Documents and Metadata. The Documents and Metadata can be in separate buckets, but it is advised to keep them (together with the JSONL created later in this notebook) in the same temporary bucket for the ease of cleanup.\n",
+ "\n",
+ "You can find more information regarding the `location` of datastores and associated limitations [here](https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store).\n",
+ "\n",
+ "The location of a Datastore is set at the time of creation and it should be called appropriately to query the Datastore.\n",
+ "\n",
+ "`FILE_NAME_VAIS_OUTPUT` is used to upload the Chunked Document to the bucket specified."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "_wsHOE5dl_3i"
+ },
+ "outputs": [],
+ "source": [
+ "PROJECT_ID = \"\" # @param {type:\"string\"}\n",
+ "\n",
+ "# Vertex AI Search Parameters\n",
+ "DATASTORE_ID = \"goog_earnings_test\" # @param {type:\"string\"}\n",
+ "LOCATION = \"global\" # @param [\"global\", \"us\", \"eu\"] Global is preferred\n",
+ "GCS_BUCKET = 'sample_earnings' # @param {type:\"string\"}\n",
+ "FILE_NAME_VAIS_OUTPUT = 'chunked_doc_from_VAIS.json' # @param {type:\"string\"}"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "nwHJzjwbTlF_"
+ },
+ "source": [
+ "# STEP 1. Create VAIS Datastore\n",
+ "\n",
+ "You can skip this section if you already have a datastore with your target unstructured documents ingested with [Chunk mode](https://cloud.google.com/generative-ai-app-builder/docs/parse-chunk-documents), which indexes your data as chunks to improve relevance and decrease computational load for LLMs."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "v-soe_CgVnFb"
+ },
+ "source": [
+ "## Helper functions to create a Datastore\n",
+ "\n",
+ "The datastore is created with [Chunk Mode](https://cloud.google.com/generative-ai-app-builder/docs/parse-chunk-documents) and Chunk size of 500 tokens.\n",
+ "\n",
+ "The documents will be processed with Layout parser (higher quality for complex documents containing elements like tables and lists) and Ancestor information (i.e. headings) is included with each Chunk. Please see [official documentation](https://cloud.google.com/generative-ai-app-builder/docs/parse-chunk-documents) for more details."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "BG1sHc6hWH86"
+ },
+ "outputs": [],
+ "source": [
+ "def create_chunk_mode_datastore(project_id: str, location: str, datastore_id: str) -> int:\n",
+ " \"\"\"Create a datastore with chunk mode and the more advanced layout parser\"\"\"\n",
+ " payload = {\n",
+ " \"displayName\": datastore_id,\n",
+ " \"industryVertical\": \"GENERIC\",\n",
+ " \"solutionTypes\": [\"SOLUTION_TYPE_SEARCH\"],\n",
+ " \"contentConfig\": \"CONTENT_REQUIRED\",\n",
+ " \"documentProcessingConfig\": {\n",
+ " \"chunkingConfig\": {\n",
+ " \"layoutBasedChunkingConfig\": {\n",
+ " \"chunkSize\": 500,\n",
+ " \"includeAncestorHeadings\": True,\n",
+ " }\n",
+ " },\n",
+ " \"defaultParsingConfig\": {\n",
+ " \"layoutParsingConfig\": {}\n",
+ " }\n",
+ " }\n",
+ " }\n",
+ " header = {\"X-Goog-User-Project\": project_id, \"Content-Type\": \"application/json\"}\n",
+ " es_endpoint = f\"https://discoveryengine.googleapis.com/v1/projects/{project_id}/locations/{location}/collections/default_collection/dataStores?dataStoreId={datastore_id}\"\n",
+ " response = authed_session.post(es_endpoint, data=json.dumps(payload), headers=header)\n",
+ " if response.status_code == 200:\n",
+ " print(f\"The creation of Datastore {datastore_id} is initiated.\")\n",
+ " print(\"It may take a few minutes for the Datastore to become available\")\n",
+ " else:\n",
+ " print(f\"Failed to create Datastore {datastore_id}\")\n",
+ " print(response.json())\n",
+ " return response.status_code"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "w2q8UZxwRd1m"
+ },
+ "source": [
+ "## Helper functions to issue basic search on a Datastore"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "98bc0zgCWhqP"
+ },
+ "outputs": [],
+ "source": [
+ "def search_by_datastore(project_id: str, location: str, datastore_id: str, query: str) -> requests.Response:\n",
+ " \"\"\"Searches a datastore using the provided query.\"\"\"\n",
+ " response = authed_session.post(\n",
+ " f'https://discoveryengine.googleapis.com/v1/projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{datastore_id}/servingConfigs/default_search:search',\n",
+ " headers={\n",
+ " 'Content-Type': 'application/json',\n",
+ " },\n",
+ " json={\n",
+ " \"query\": query,\n",
+ " \"pageSize\": 1\n",
+ " },\n",
+ " )\n",
+ " return response"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "fJ3ULZOeR-E2"
+ },
+ "source": [
+ "## Helper functions to check whether or not a Datastore already exists"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "ShppuvcxWBut"
+ },
+ "outputs": [],
+ "source": [
+ "def datastore_exists(project_id: str, location: str, datastore_id: str) -> bool:\n",
+ " \"\"\"Check if a datastore exists.\"\"\"\n",
+ " response = search_by_datastore(project_id, location, datastore_id, \"test\")\n",
+ " status_code = response.status_code\n",
+ " if status_code == 200:\n",
+ " return True\n",
+ " if status_code == 404:\n",
+ " return False\n",
+ " raise Exception(f\"Error: {status_code}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "NnCzxjV9SVO_"
+ },
+ "source": [
+ "## Create a Datastore with the provided ID if it doesn't exist"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "nBnAc1NIV59z"
+ },
+ "outputs": [],
+ "source": [
+ "# Create Chunk mode Datastore if it doesn't exist\n",
+ "if datastore_exists(PROJECT_ID, LOCATION, DATASTORE_ID):\n",
+ " print(f\"Datastore {DATASTORE_ID} already exists.\")\n",
+ "else:\n",
+ " create_chunk_mode_datastore(PROJECT_ID, LOCATION, DATASTORE_ID)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "MF07QdwxW_1n"
+ },
+ "source": [
+ "## [Optional] Check if the Datastore is created successfully\n",
+ "\n",
+ "\n",
+ "The Datastore is polled to track when it becomes available.\n",
+ "\n",
+ "This may take a few minutes after the datastore creation is initiated"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "S7xR3uX8XEnH"
+ },
+ "outputs": [],
+ "source": [
+ "while not datastore_exists(PROJECT_ID, LOCATION, DATASTORE_ID):\n",
+ " print(f\"Datastore {DATASTORE_ID} is still being created.\")\n",
+ " time.sleep(30)\n",
+ "print(f\"Datastore {DATASTORE_ID} is created successfully.\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "Gxyl1Fs2XXBp"
+ },
+ "source": [
+ "# STEP 2. Import sample document into VAIS Datastore"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "IRaL_VoXTnIw"
+ },
+ "source": [
+ "## Create a GCS bucket with sample document(s)\n",
+ "\n",
+ "This step is only needed for the purpose of this demo. For the real use case you will need to upload your actual documents to a GCS bucket\n",
+ "\n",
+ "Here, we download [Alphabet's 2024 Q2 Earnings Release](https://abc.xyz/assets/19/e4/3dc1d4d6439c81206370167db1bd/2024q2-alphabet-earnings-release.pdf) as a sample document."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "HHVR3KkzT2H4"
+ },
+ "outputs": [],
+ "source": [
+ "def create_gcs_bucket_and_download_files(project_id: str, bucket_name: str, file_urls: List[str]) -> None:\n",
+ " \"\"\"\n",
+ " Creates a GCS bucket (if it doesn't exist) and downloads files from specified URLs.\n",
+ "\n",
+ " Args:\n",
+ " project_id (str): Your Google Cloud Project ID.\n",
+ " bucket_name (str): The name of the GCS bucket (e.g., \"my-documents-bucket\").\n",
+ " file_urls (list): A list of URLs to files you want to download.\n",
+ " \"\"\"\n",
+ "\n",
+ " storage_client = storage.Client(project=project_id)\n",
+ " bucket = storage_client.bucket(bucket_name)\n",
+ "\n",
+ " if not bucket.exists():\n",
+ " bucket = storage_client.create_bucket(bucket_name)\n",
+ "\n",
+ " print(f\"Bucket {bucket_name} created.\")\n",
+ "\n",
+ "\n",
+ " for url in file_urls:\n",
+ " file_name = url.split(\"/\")[-1]\n",
+ " print(f\"Downloading: {file_name}\")\n",
+ "\n",
+ " try:\n",
+ " response = requests.get(url)\n",
+ " response.raise_for_status() # Raise an exception for HTTP errors\n",
+ "\n",
+ " blob = bucket.blob(file_name)\n",
+ " blob.upload_from_string(\n",
+ " response.content,\n",
+ " content_type='application/pdf' # Explicitly set the content type\n",
+ " )\n",
+ " print(f\"Uploaded: {file_name}\")\n",
+ " except requests.exceptions.RequestException as e:\n",
+ " print(f\"Error downloading {file_name}: {e}\")\n",
+ "\n",
+ "\n",
+ "file_urls = [\n",
+ " \"https://abc.xyz/assets/19/e4/3dc1d4d6439c81206370167db1bd/2024q2-alphabet-earnings-release.pdf\"\n",
+ "]\n",
+ "\n",
+ "create_gcs_bucket_and_download_files(PROJECT_ID, GCS_BUCKET, file_urls)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "js_EG6U2XaKL"
+ },
+ "source": [
+ "## Helper function to import documents into a VAIS Datastroe\n",
+ "\n",
+ "This helper function is used to import the documents in a GCS folder into VAIS\n",
+ "\n",
+ "NOTE: The [\"dataSchema\"](https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/GcsSource?hl=en) should be specified as \"content\". This allows us to ingest PDF files directly. The default \"dataSchema\" is \"document\" which expects JSONL files(s) in `gcs_uri`. This option is most useful when we want to include Metadata. See [documentation](https://cloud.google.com/generative-ai-app-builder/docs/prepare-data?hl=en#storage-unstructured) for more details.\n",
+ "\n",
+ "The process is done asynchronously, and the request returns an instance of a \"Long running Operation\".\n",
+ "\n",
+ "For a small corpus like the one we are experimenting with in this notebook, the process takes in the order of xx minutes."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "a2EnwXpOXlj3"
+ },
+ "outputs": [],
+ "source": [
+ "def import_documents_from_gcs(project_id: str, location: str, datastore_id: str, gcs_uri: str) -> str:\n",
+ " \"\"\"Imports unstructured documents from a GCS bucket.\"\"\"\n",
+ " payload = {\n",
+ " \"reconciliationMode\": \"INCREMENTAL\",\n",
+ " \"gcsSource\": {\"inputUris\": [gcs_uri],\n",
+ " \"dataSchema\": \"content\"},\n",
+ " }\n",
+ " header = {\"Content-Type\": \"application/json\"}\n",
+ " es_endpoint = f\"https://discoveryengine.googleapis.com/v1/projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{datastore_id}/branches/default_branch/documents:import\"\n",
+ " response = authed_session.post(es_endpoint, data=json.dumps(payload), headers=header)\n",
+ " print(f\"--{response.json()}\")\n",
+ " return response.json()[\"name\"]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "NrypDv7kXtLf"
+ },
+ "source": [
+ "## Importing sample documents into the Chunk Mode Datastore"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "qzKBkp9bXxZT"
+ },
+ "outputs": [],
+ "source": [
+ "chunk_mode_import_lro = import_documents_from_gcs(\n",
+ " project_id=PROJECT_ID,\n",
+ " location=LOCATION,\n",
+ " datastore_id=DATASTORE_ID,\n",
+ " gcs_uri=f'gs://{GCS_BUCKET}/*',\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "0SmHf6ZfX3GI"
+ },
+ "source": [
+ "## [Optional] Check the status of document import for the Chunk Mode Datastore\n",
+ "Optionally check the status of the long running operation for the import job. You can check this in the UI as well by looking at the \"activity\" tab of the corresponding Datastore"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "L_ID_6ozX5-u"
+ },
+ "outputs": [],
+ "source": [
+ "while True:\n",
+ " response = authed_session.get(\n",
+ " f\"https://discoveryengine.googleapis.com/v1/{chunk_mode_import_lro}\",\n",
+ " )\n",
+ " try:\n",
+ " status = response.json()[\"done\"]\n",
+ " if status:\n",
+ " print(f\"Import completed!\")\n",
+ " break\n",
+ " except KeyError:\n",
+ " print(f\"Import in progress.\")\n",
+ " time.sleep(60)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "ndoKhd9lguyc"
+ },
+ "source": [
+ "#Helper Functions for formatting and ease of visual inspection\n",
+ "The following helper functions are used to reconstruct a document from its chunks and to show them in a human-friendly manner.\n",
+ "\n",
+ "These functions are not particularly related to VAIS and you do not need to worry about their details to understand the flow of this notebook"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "XLT8IvSMXG58"
+ },
+ "source": [
+ "##Helper function to beautify JSON outputs"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "kkZiVM8nR53S"
+ },
+ "outputs": [],
+ "source": [
+ "def parse_and_print_json(data: Dict[str, Any]) -> Dict[str, Any] | None:\n",
+ " \"\"\"\n",
+ " Recursively parses and structures JSON data into a more readable dictionary format,\n",
+ " handling nested dictionaries.\n",
+ "\n",
+ " Args:\n",
+ " data (dict): The dictionary potentially containing JSON strings at any level.\n",
+ "\n",
+ " Returns:\n",
+ " dict or None: The original dictionary with JSON strings parsed into dictionaries,\n",
+ " or None if there's an error during JSON decoding.\n",
+ " \"\"\"\n",
+ "\n",
+ " for key, value in data.items():\n",
+ " if isinstance(value, str) and value.startswith('{'): # Check for JSON string\n",
+ " try:\n",
+ " data[key] = json.loads(value) # Parse and replace with the parsed dictionary\n",
+ " except json.JSONDecodeError as e:\n",
+ " print(f\"Error decoding JSON in key '{key}': {e}\")\n",
+ " return None\n",
+ " elif isinstance(value, dict): # Recurse into nested dictionaries\n",
+ " result = parse_and_print_json(value)\n",
+ " if result is None: # If an error occurred during recursion, propagate it\n",
+ " return None\n",
+ "\n",
+ " return data\n",
+ "\n",
+ "def print_json(data: Dict[str, Any]) -> Dict[str, Any]:\n",
+ " \"\"\"\n",
+ " Structures the JSON data into a more readable dictionary format\n",
+ "\n",
+ " Args:\n",
+ " data (dict): The parsed JSON data as a dictionary.\n",
+ "\n",
+ " Returns:\n",
+ " dict: The structured JSON data\n",
+ " \"\"\"\n",
+ " output = {}\n",
+ "\n",
+ " for key, value in data.items():\n",
+ " if isinstance(value, dict):\n",
+ " output[key] = print_json(value)\n",
+ " elif isinstance(value, list):\n",
+ " output[key] = [\n",
+ " print_json(item) if isinstance(item, dict) else item for item in value\n",
+ " ]\n",
+ " else:\n",
+ " output[key] = value\n",
+ "\n",
+ " return output\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "ZPZl6Qiag2ML"
+ },
+ "source": [
+ "##Helper function to reconstruct a document from chunks\n",
+ "\n",
+ "Stitch chunks together to reconstruct the document while including pointers for chunk start and end."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "yMa-PpoxhVEa"
+ },
+ "outputs": [],
+ "source": [
+ "def reconstruct_document(chunked_document: Dict[str, Any]) -> str:\n",
+ " \"\"\"Reconstructs a document from its chunks.\"\"\"\n",
+ " reconstructed_document = \"\"\n",
+ " for chunk in chunked_document['jsonData']['chunks']:\n",
+ " reconstructed_document += \"Start of chunk: \" + chunk[\"id\"] + \"\\n\\n\"\n",
+ " reconstructed_document += chunk[\"content\"]\n",
+ " reconstructed_document += \"\\n\\nEnd of chunk: \" + chunk[\"id\"] + \"\\n\\n\"\n",
+ "\n",
+ " return reconstructed_document"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "d1WK0DUEjd39"
+ },
+ "source": [
+ "## Helper function to beautify a Markdown Table\n",
+ "\n",
+ "Takes the markdown table from chunks and makes it more human readable using appropriate column widths using pipes and horizontal separators."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "J5VOpJyKhDdP"
+ },
+ "outputs": [],
+ "source": [
+ "def format_markdown_table(table: str, max_cell_width: int = 15) -> str:\n",
+ " \"\"\"Formats a poorly formatted Markdown table with aligned pipes,\n",
+ " horizontal separators, and cell value wrapping.\n",
+ "\n",
+ " Args:\n",
+ " table: A string containing the poorly formatted Markdown table.\n",
+ " max_cell_width: The maximum allowed width for each cell.\n",
+ "\n",
+ " Returns:\n",
+ " A string containing the nicely formatted Markdown table with\n",
+ " wrapped cell values.\n",
+ " \"\"\"\n",
+ "\n",
+ " # Split the table into rows.\n",
+ " rows = table.strip().split('\\n')\n",
+ "\n",
+ " # Find the actual header row (skipping rows with only hyphens)\n",
+ " header_row_index = next(\n",
+ " (i for i, row in enumerate(rows) if not all(cell.strip() == '-' for cell in row.strip().split('|')[1:-1])),\n",
+ " 0 # Default to the first row if no suitable header is found\n",
+ " )\n",
+ "\n",
+ " # Split each row into cells, ensuring empty cells are accounted for\n",
+ " cells_per_row = [\n",
+ " [cell.strip() for cell in row.strip().split('|')[1:-1]] # Remove leading and trailing pipes before splitting\n",
+ " for row in rows\n",
+ " ]\n",
+ "\n",
+ " # Determine the number of columns, considering both header and data rows\n",
+ " num_columns = max(len(row) for row in cells_per_row)\n",
+ "\n",
+ " # Determine the maximum width of each column, considering the max_cell_width limit.\n",
+ " column_widths = [\n",
+ " min(\n",
+ " max(len(cells_per_row[row_index][col_index])\n",
+ " for row_index in range(len(cells_per_row))\n",
+ " if col_index < len(cells_per_row[row_index])), # Handle rows with fewer columns\n",
+ " max_cell_width\n",
+ " )\n",
+ " for col_index in range(num_columns)\n",
+ " ]\n",
+ "\n",
+ " # Set a minimum column width to prevent 0 width\n",
+ " min_column_width = 3 # Or any other reasonable minimum\n",
+ " column_widths = [max(width, min_column_width) for width in column_widths]\n",
+ "\n",
+ " # Function to wrap cell values if they exceed the column width\n",
+ " def wrap_cell_value(cell_value, width):\n",
+ " wrapped_lines = textwrap.wrap(cell_value, width=width)\n",
+ " return wrapped_lines\n",
+ "\n",
+ " # Format the header row, potentially adding empty cells if needed\n",
+ " formatted_header_cells = [wrap_cell_value(cell, column_widths[i]) for i, cell in enumerate(cells_per_row[header_row_index])]\n",
+ " formatted_header_cells += [['']] * (num_columns - len(formatted_header_cells)) # Add empty cells if needed\n",
+ " max_lines_in_header = max(len(lines) for lines in formatted_header_cells)\n",
+ " formatted_header_rows = []\n",
+ " for line_index in range(max_lines_in_header):\n",
+ " formatted_header_rows.append('| ' + ' | '.join(\n",
+ " (cell[line_index] if line_index < len(cell) else '') + ' ' * (column_widths[i] - len(cell[line_index] if line_index < len(cell) else ''))\n",
+ " for i, cell in enumerate(formatted_header_cells)) + ' |')\n",
+ "\n",
+ " formatted_rows = formatted_header_rows\n",
+ "\n",
+ " # Format the separator row beneath the header.\n",
+ " formatted_rows.append('|' + '|'.join(\n",
+ " '-' * (width + 2) for width in column_widths) + '|')\n",
+ "\n",
+ " # Format the remaining rows (excluding the hyphen-only row if present), adding separators after each row\n",
+ " for row_index, row in enumerate(cells_per_row):\n",
+ " if row_index != header_row_index and not all(cell.strip() == '-' for cell in row): # Skip header and hyphen-only rows\n",
+ " # Pad row with empty cells if needed\n",
+ " padded_row = row + [''] * (num_columns - len(row))\n",
+ " wrapped_cells = [wrap_cell_value(cell, column_widths[i]) for i, cell in enumerate(padded_row)]\n",
+ " max_lines_in_row = max(len(lines) for lines in wrapped_cells)\n",
+ " for line_index in range(max_lines_in_row):\n",
+ " formatted_row = '| ' + ' | '.join(\n",
+ " (cell[line_index] if line_index < len(cell) else '') + ' ' * (column_widths[i] - len(cell[line_index] if line_index < len(cell) else ''))\n",
+ " for i, cell in enumerate(wrapped_cells)) + ' |'\n",
+ " formatted_rows.append(formatted_row)\n",
+ "\n",
+ " # Add separator row after each data row (except the last one)\n",
+ " if row_index < len(cells_per_row) - 1:\n",
+ " formatted_rows.append('|' + '|'.join(\n",
+ " '-' * (width + 2) for width in column_widths) + '|')\n",
+ "\n",
+ " # Join the formatted rows into a single string.\n",
+ " return '\\n'.join(formatted_rows)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "I-50mUGuiC_2"
+ },
+ "source": [
+ "## Helper function to beautify all Markdown Tables\n",
+ "\n",
+ "This function goes over the whole reconstructed document and replaces all markdown tables with their beautified versions"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true,
+ "id": "GKxnoDn9hHA1"
+ },
+ "outputs": [],
+ "source": [
+ "def format_chunked_document(text: str) -> str:\n",
+ " \"\"\"Identifies markdown tables within a string, formats them, and replaces the original instances.\n",
+ "\n",
+ " Args:\n",
+ " text: The input string potentially containing multiple markdown tables.\n",
+ "\n",
+ " Returns:\n",
+ " The modified string with formatted markdown tables replacing the original ones.\n",
+ " \"\"\"\n",
+ "\n",
+ " # Define the pattern to match markdown table instances\n",
+ " table_pattern = r\"_START_OF_TABLE_\\nTABLE_IN_MARKDOWN:\\n(.*?)\\n_END_OF_TABLE_\"\n",
+ "\n",
+ " # Find all matches of the pattern within the text\n",
+ " matches = re.findall(table_pattern, text, re.DOTALL) # re.DOTALL allows '.' to match newlines\n",
+ "\n",
+ " # Process each matched table and replace it in the original text\n",
+ " for table_content in matches:\n",
+ " formatted_table = format_markdown_table(table_content)\n",
+ " # Remove the extra newline before inserting the formatted table\n",
+ " text = text.replace(f\"_START_OF_TABLE_\\nTABLE_IN_MARKDOWN:\\n{table_content}\\n_END_OF_TABLE_\", \"\\n\" + formatted_table + \"\\n\\n\", 1)\n",
+ "\n",
+ " return text\n",
+ "\n",
+ "\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "nkWefjvj-NGn"
+ },
+ "source": [
+ "# STEP 3. Get Parsed and Chunked Document\n",
+ "\n",
+ "In this section we visually review Parsed and Chunked versions of a document"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "jspb2xq2ab_F"
+ },
+ "source": [
+ "##List all documents in a Datastore\n",
+ "Get a list of all documents in the datastore. You can then select the ID for the document of interest."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "281LTsCrabCX"
+ },
+ "outputs": [],
+ "source": [
+ "def list_documents_datastore(project_id: str, location: str, data_store_id: str) -> List[Dict[str, str]] | None:\n",
+ " \"\"\"Lists documents in a specified data store using the REST API.\n",
+ "\n",
+ " Args:\n",
+ " project_id: The ID of your Google Cloud project.\n",
+ " location: The location of your data store.\n",
+ " Values: \"global\", \"us\", \"eu\"\n",
+ " data_store_id: The ID of the datastore.\n",
+ "\n",
+ " Returns:\n",
+ " The JSON response containing the list of documents, or None if an error occurs.\n",
+ " \"\"\"\n",
+ "\n",
+ " base_url = f\"{location}-discoveryengine.googleapis.com\" if location != \"global\" else \"discoveryengine.googleapis.com\"\n",
+ " url = f\"https://{base_url}/v1alpha/projects/{project_id}/locations/{location}/collections/default_collection/dataStores/{data_store_id}/branches/default_branch/documents\"\n",
+ "\n",
+ " try:\n",
+ " # Assuming 'authed_session' is available and properly configured for authentication\n",
+ " response = authed_session.get(url)\n",
+ " response.raise_for_status() # Raise an exception for bad status codes\n",
+ " documents = response.json()\n",
+ " print(f\"Successfully retrieved {len(documents.get('documents', []))} document(s).\\n\")\n",
+ " return [{'id': document['id'], 'uri': document['content']['uri']}\n",
+ " for document in documents.get('documents', [])]\n",
+ "\n",
+ " except requests.exceptions.RequestException as e:\n",
+ " print(f\"Error listing documents: {e}\")\n",
+ " return None\n",
+ "\n",
+ "list_documents_datastore(PROJECT_ID, LOCATION, DATASTORE_ID)\n",
+ "DOCUMENT_ID = list_documents_datastore(PROJECT_ID, LOCATION, DATASTORE_ID)[0]['id'] # provisionally take the first document in the datastore as the document we want to analyze"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "OMFcf4zPiZ6N"
+ },
+ "source": [
+ "##Select the Document of interest\n",
+ "By runnng the previous block, the Document ID of interest will be pre-set to the first document in the Datastore.\n",
+ "\n",
+ "You can update as needed.\n",
+ "\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "h6xUzPqQcR3o"
+ },
+ "outputs": [],
+ "source": [
+ "DOCUMENT_ID = \"\" # @param {type:\"string\"}"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "c7h6PhYr-R-F"
+ },
+ "source": [
+ "## Get the Parsed Document\n",
+ "\n",
+ "Get the parsed version of the document of interest.\n",
+ "\n",
+ "The parsed document is not really human readable. However it might be useful to troubleshoot downstream issues such as text element identification or cell block detection.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "HJ_mtgCxmNv7"
+ },
+ "outputs": [],
+ "source": [
+ "def get_parsed_document(project_id: str, data_store_id: str, document_id: str) -> Dict[str, Any] | None:\n",
+ " \"\"\"Retrieves a parsed document in JSON from Vertex AI Agent Builder.\"\"\"\n",
+ " \"\"\"Only applicable for data stores with Chunking config set.\"\"\"\n",
+ "\n",
+ " # Get authentication token (replace with your method)\n",
+ " access_token = creds.token # Use gcloud or service account\n",
+ "\n",
+ " base_url = \"https://discoveryengine.googleapis.com/v1alpha\"\n",
+ " url = f\"{base_url}/projects/{project_id}/locations/global/collections/default_collection/dataStores/{data_store_id}/branches/0/documents/{document_id}:getProcessedDocument?processed_document_type=PARSED_DOCUMENT\"\n",
+ " response = authed_session.get(url)\n",
+ "\n",
+ " if response.status_code == 200:\n",
+ " parsed_document = parse_and_print_json(response.json())\n",
+ " return parsed_document\n",
+ " else:\n",
+ " print(f\"Error: {response.status_code}, {response.text}\")\n",
+ " return None\n",
+ "\n",
+ "parsed_document = get_parsed_document(PROJECT_ID, DATASTORE_ID, DOCUMENT_ID)\n",
+ "parsed_document"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "heR9Ebfix3hD"
+ },
+ "source": [
+ "##Get the Chunked Document\n",
+ "\n",
+ "Get Chunks from the document in JSON format"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "aHGruIcax7ij"
+ },
+ "outputs": [],
+ "source": [
+ "def get_chunked_document(project_id: str, data_store_id: str, document_id: str) -> Dict[str, Any] | None:\n",
+ " \"\"\"Retrieves a chunked document in JSON from Vertex AI Agent Builder.\"\"\"\n",
+ " \"\"\"Only applicable for data stores with Chunking config set.\"\"\"\n",
+ "\n",
+ " # Get authentication token (replace with your method)\n",
+ " access_token = creds.token # Use gcloud or service account\n",
+ "\n",
+ " base_url = \"https://discoveryengine.googleapis.com/v1alpha\"\n",
+ " url = f\"{base_url}/projects/{project_id}/locations/global/collections/default_collection/dataStores/{data_store_id}/branches/0/documents/{document_id}:getProcessedDocument?processed_document_type=CHUNKED_DOCUMENT\"\n",
+ " response = authed_session.get(url)\n",
+ "\n",
+ " if response.status_code == 200:\n",
+ " chunked_document = parse_and_print_json(response.json())\n",
+ " return chunked_document\n",
+ " else:\n",
+ " print(f\"Error: {response.status_code}, {response.text}\")\n",
+ " return None\n",
+ "\n",
+ "chunked_document = get_chunked_document(PROJECT_ID, DATASTORE_ID, DOCUMENT_ID)\n",
+ "chunked_document"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "t1gLR_5cN-3-"
+ },
+ "source": [
+ "## Visually review the Chunked document\n",
+ "\n",
+ "Visually review to spot issues with the chunked document.\n",
+ "\n",
+ "The chunks from JSON object are stacked together first, and beautified later for ease of human reviewing.\n",
+ "\n",
+ "Helper functions defined earlier in this notebook are used here.\n",
+ "\n",
+ "For offline reviewing, you can export the string `chunked_document` to your desired format (e.g. PDF)\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "i6Oy79QnFqHm"
+ },
+ "outputs": [],
+ "source": [
+ "reconstructed_document = reconstruct_document(chunked_document)\n",
+ "processed_string = format_chunked_document(reconstructed_document)\n",
+ "print(processed_string)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "68QbshVtqTXj"
+ },
+ "source": [
+ "The beautified chunked version of the sample document use in this notebook will begin like the screenshot below:\n",
+ "\n",
+ ""
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "65AKofzIuU2t"
+ },
+ "source": [
+ "## [Optional] Upload Chunks to GCS Bucket\n",
+ "\n",
+ "Upload chunked document for offline review and edit.\n",
+ "\n",
+ "You can always transform JSON to your preferred formats (e.g. CSV, XLSX) before exporting."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "e95_7EcOs1Vt"
+ },
+ "outputs": [],
+ "source": [
+ "def upload_json_to_gcs(bucket_name: str, file_name: str, json_data: Dict[str, Any] | List[Any]) -> None:\n",
+ " \"\"\"Uploads a JSON variable to a GCS bucket as a file.\n",
+ "\n",
+ " Args:\n",
+ " bucket_name: The name of the GCS bucket (must start with 'gs://' and end with '/').\n",
+ " file_name: The desired name of the JSON file within the bucket.\n",
+ " json_data: The JSON data to be uploaded (Python dictionary or list).\n",
+ "\n",
+ " Raises:\n",
+ " ValueError: If the bucket_name format is invalid.\n",
+ " \"\"\"\n",
+ "\n",
+ " if not bucket_name.startswith(\"gs://\") or not bucket_name.endswith(\"/\"):\n",
+ " raise ValueError(\n",
+ " \"Invalid GCS path format. Must start with 'gs://' and end with '/'. \"\n",
+ " f\"Received: '{bucket_name}'\"\n",
+ " )\n",
+ "\n",
+ " storage_client = storage.Client(project=PROJECT_ID) # Assuming PROJECT_ID is defined\n",
+ "\n",
+ " parsed_path = urlparse(bucket_name)\n",
+ " bucket_name = parsed_path.netloc\n",
+ "\n",
+ " bucket = storage_client.bucket(bucket_name)\n",
+ " blob = bucket.blob(file_name)\n",
+ "\n",
+ " # Convert the JSON data to a string\n",
+ " json_string = json.dumps(json_data,indent=2)\n",
+ "\n",
+ " # Upload the JSON string as the file contents\n",
+ " blob.upload_from_string(json_string, content_type='application/json')\n",
+ "\n",
+ " print(f\"JSON data uploaded to https://storage.mtls.cloud.google.com/{bucket_name}/{file_name}\\n\")\n",
+ "\n",
+ "upload_json_to_gcs(\"gs://\" + GCS_BUCKET + \"/\", FILE_NAME_VAIS_OUTPUT, chunked_document['jsonData'])\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "9yM5bnVvvOxi"
+ },
+ "source": [
+ "# STEP 4. [Needs Allowlisting] Bring Your Own Chunks (BYOC)\n",
+ "\n",
+ "This section describes how to [bring your own chunks](https://cloud.google.com/generative-ai-app-builder/docs/parse-chunk-documents#bring-chunks) into VAIS.\n",
+ "\n",
+ "The chunks can be completely generated by you, or you can take chunks generated by VAIS and modify them. Examples of the latter could be augmenting with additional context, or even batch processing to fix systematic issues with a certain document template like heading detection.\n",
+ "\n",
+ "Note that chunks should comply with the token limit specified at the time of creating the Datastore.\n",
+ "\n",
+ "At the time of publishing this notebook, the BYOC feature is available under private preview. To be allowlisted for this feature, please contact your Google account team.\n",
+ "\n",
+ "Additional Notes:\n",
+ "\n",
+ "1. This notebook showcases a particular use case of BYOC where VAIS is used for the initial parsing and chunking as well. In most cases for BYOC parsing and chunking is done outside VAIS and the chunks are brought into VAIS using BYOC.\n",
+ "\n",
+ "2. A document ingested using this feature is of type JSON and is treated separately from the original document used to generate the chunks (assuming that part is done in VAIS as well). To avoid duplicates, the original file needs to be removed after the BYOC document is ingested. You can use [this](https://github.com/GoogleCloudPlatform/applied-ai-engineering-samples/blob/main/genai-on-vertex-ai/vertex_ai_search/inline_ingestion_of_documents.ipynb) notebook to see how to delete a specific document via API.\n",
+ "\n",
+ "3. If you use VAIS to do the initial chunking, the `docuemnt metadata` will reference the original source document and its title. `document metadata` field in the chunked document is **only** used for retrieval purposes. You can modify that field as desired if you want to leverage it for other purposes.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "fb8JrGgnxP73"
+ },
+ "source": [
+ "## Function to import Chunks"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "A39akvzx89cA"
+ },
+ "outputs": [],
+ "source": [
+ "def upload_document_chunks(project_id: str, data_store_id: str, uri_path: str) -> None:\n",
+ " \"\"\"Uploads chunks of a document to a Vertex AI data store.\"\"\"\n",
+ "\n",
+ " # Get authentication token using gcloud\n",
+ " access_token = creds.token # Use gcloud or service account\n",
+ "\n",
+ " base_url = \"https://discoveryengine.googleapis.com/v1alpha\"\n",
+ " url = f\"{base_url}/projects/{project_id}/locations/global/collections/default_collection/dataStores/{data_store_id}/branches/default_branch/documents:import\"\n",
+ "\n",
+ " # Prepare the request payload\n",
+ " header = {\"Content-Type\": \"application/json\"}\n",
+ " payload = {\n",
+ " \"reconciliationMode\": \"INCREMENTAL\",\n",
+ " \"gcsSource\": {\"inputUris\": uri_path,\n",
+ " \"dataSchema\": \"content\"},\n",
+ " }\n",
+ "\n",
+ " response = authed_session.post(url=url,json=payload)\n",
+ "\n",
+ " if response.status_code == 200:\n",
+ " print(\"Chunked file uploaded successfully!\")\n",
+ " else:\n",
+ " print(f\"Error uploading chunked file: {response.status_code}, {response.text}\")\n",
+ "\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "EjMOrPkty7PR"
+ },
+ "source": [
+ "## Import Chunks\n",
+ "\n",
+ "Define the file name with chunks to be imported and run the function to actually import it.\n",
+ "\n",
+ "The formatting of the file should be same as `jsonData` field in the Chunked document.\n",
+ "\n",
+ "For the sake of quick testing you use the exported chunked document here and reimport it into VAIS."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "Klnz7UCsyWzF"
+ },
+ "outputs": [],
+ "source": [
+ "FILE_NAME_TO_IMPORT = 'chunked_doc_to_import.json' # @param {type:\"string\"}\n",
+ "upload_document_chunks(PROJECT_ID, DATASTORE_ID,\"gs://\" + GCS_BUCKET + \"/\" + FILE_NAME_TO_IMPORT)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "QVJ5iIf4cuOC"
+ },
+ "source": [
+ "## Visually review BYO Chunked document\n",
+ "\n",
+ "Follow the instructions under step 3 to\n",
+ "\n",
+ "- List documents in the datastore\n",
+ "- Identify the BYO chunked document\n",
+ "- Get the chunked document, and use helper fucntions to stack the chunks together and visually review it.\n",
+ "\n",
+ "The screenshot below shows what you can get by slightly modifying the chunked document by VAIS and ingesting it back into VAIS (Note that the first line is manually added to the first chunk).\n",
+ "\n",
+ ""
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "b_9s1JT6AS7o"
+ },
+ "source": [
+ "#Cleanup\n",
+ "Clean up resources created in this notebook.\n",
+ "\n",
+ "Set `DELETE_RESOURCES` flag to `True` to delete resources."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "9yeinaBzeok9"
+ },
+ "outputs": [],
+ "source": [
+ "DELETE_RESOURCES = False"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "sS7tVxEgAXGA"
+ },
+ "source": [
+ "## Clean up GCS bucket\n",
+ "\n",
+ "❗❗❗ Only run the below cells if you created a new bucket just for this notebook ❗❗❗\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "dAOJ46asAuoa"
+ },
+ "outputs": [],
+ "source": [
+ "def empty_bucket(bucket_name: str) -> None:\n",
+ " \"\"\"Deletes all objects in the specified GCS bucket.\"\"\"\n",
+ " client = storage.Client()\n",
+ " bucket = client.get_bucket(bucket_name)\n",
+ "\n",
+ " blobs = bucket.list_blobs() # List all blobs (objects)\n",
+ " for blob in blobs:\n",
+ " blob.delete() # Delete each blob\n",
+ "\n",
+ " print(f\"Bucket {bucket_name} emptied.\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "DoIjtak6Ab7O"
+ },
+ "outputs": [],
+ "source": [
+ "if DELETE_RESOURCES:\n",
+ " ## Empty the bucket by deleting all files in it\n",
+ " empty_bucket(GCS_BUCKET)\n",
+ "\n",
+ " ## Create a client object\n",
+ " client = storage.Client(project=PROJECT_ID)\n",
+ "\n",
+ " ## Get the bucket object\n",
+ " bucket = client.get_bucket(GCS_BUCKET)\n",
+ "\n",
+ " ## Delete the bucket\n",
+ " bucket.delete()\n",
+ "\n",
+ " print(f\"Bucket {GCS_BUCKET} deleted successfully.\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "id": "L0aU2DdTckUo"
+ },
+ "source": [
+ "## Delete the Datastore\n",
+ "Delete the Datastore if you no longer need it\n",
+ "\n",
+ "Alternatively you can follow [these instructions](https://console.cloud.google.com/gen-app-builder/data-stores) to delete a Datastore from the UI"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "id": "pBKcL_oicjxL"
+ },
+ "outputs": [],
+ "source": [
+ "if DELETE_RESOURCES:\n",
+ " response = authed_session.delete(\n",
+ " f'https://discoveryengine.googleapis.com/v1alpha/projects/{PROJECT_ID}/locations/{LOCATION}/collections/default_collection/dataStores/{DATASTORE_ID}',\n",
+ " headers={\n",
+ " \"X-Goog-User-Project\": PROJECT_ID\n",
+ " }\n",
+ " )\n",
+ "\n",
+ " print(response.json())"
+ ]
+ }
+ ],
+ "metadata": {
+ "colab": {
+ "provenance": []
+ },
+ "kernelspec": {
+ "display_name": "Python 3",
+ "name": "python3"
+ },
+ "language_info": {
+ "name": "python"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}
From 44ba53502f1a12e8007e37c32568ef2f7a1d90d7 Mon Sep 17 00:00:00 2001
From: Abhishek Bhagwat
Date: Thu, 10 Oct 2024 17:03:10 -0700
Subject: [PATCH 2/2] Automated Build of Github Pages documentation (#117)
Build GitHub pages with mkdocs
---------
Co-authored-by: Rajesh Thallam
---
.github/workflows/pages-build-deployment.yml | 34 +++
assets/aaie_favicon.png | Bin 0 -> 618780 bytes
assets/aaie_logo.png | Bin 0 -> 343872 bytes
docs/mkdocs.sh | 55 ++++
docs/mkdocs.yml | 287 +++++++++++++++++++
docs/requirements.txt | 5 +
6 files changed, 381 insertions(+)
create mode 100644 .github/workflows/pages-build-deployment.yml
create mode 100644 assets/aaie_favicon.png
create mode 100644 assets/aaie_logo.png
create mode 100755 docs/mkdocs.sh
create mode 100644 docs/mkdocs.yml
create mode 100644 docs/requirements.txt
diff --git a/.github/workflows/pages-build-deployment.yml b/.github/workflows/pages-build-deployment.yml
new file mode 100644
index 00000000..a3d8c309
--- /dev/null
+++ b/.github/workflows/pages-build-deployment.yml
@@ -0,0 +1,34 @@
+name: pages-build-deployment
+
+on:
+ [push]
+
+permissions:
+ contents: write
+
+jobs:
+ build-and-deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.x'
+
+ - name: Install dependencies
+ run: |
+ python -m pip install --upgrade pip
+ pip install -r docs/requirements.txt
+
+ - name: Configure Git
+ run: |
+ git config --global user.name "GitHub Actions Bot"
+ git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+ - name: Build and deploy documentation
+ run: |
+ cd docs
+ chmod +x ./mkdocs.sh
+ ./mkdocs.sh gh-deploy --force
diff --git a/assets/aaie_favicon.png b/assets/aaie_favicon.png
new file mode 100644
index 0000000000000000000000000000000000000000..7695420b37e86ee21c4afeddf109ad58e449a8b8
GIT binary patch
literal 618780
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%0D)=MEe+v81ASP1L}c)
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