Vertex AI client libraries in Google Distributed Cloud (GDC) air-gapped let you
programmatically access Optical Character Recognition (OCR), Speech-to-Text,
Vertex AI Translation, and Vertex AI Platform APIs without
writing raw server requests. Extract and install a client library directly from
its tar file, or import the library in a JupyterLab notebook. For more information
about notebook environments, see
[Manage notebooks](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-workbench.md.txt).

This document is for application developers in application operator groups who
configure application and development environments to enable AI features. For
more information, see
[Audiences for GDC air-gapped documentation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/audiences.md.txt).

## Vertex AI client libraries

Vertex AI offers different versions of client libraries for
CentOS and Ubuntu operating systems.

The naming conventions of Vertex AI client libraries in the tar
file are based on the operating system, the service name, and the version. The
filenames adhere to the following format:

    OS-google-cloud-SERVICE-VERSION.tar.gz

Replace the following:

- `OS`: the name of the operating system where you want to install the client library. Allowed values are `centos` and `ubuntu`.
- `SERVICE`: the name of the Vertex AI
  service from which you want to download the client library. The following are
  the allowed values:

  - `aiplatform`: the Vertex AI Platform client library.
  - `speech`: the Speech-to-Text client library.
  - `translate`: the Vertex AI Translation client library.
  - `vision`: the OCR client library.
- `VERSION`: the version number of the client library,
  such as `3.8.0`.

The following table contains the Vertex AI client libraries that
Distributed Cloud supports:

| Vertex AI service | Operating system | Filename |
|---|---|---|
| OCR | Centos | `centos-google-cloud-vision-3.0.0.tar.gz` |
| OCR | Ubuntu | `ubuntu-google-cloud-vision-3.0.0.tar.gz` |
| Speech-to-Text | Centos | `centos-google-cloud-speech-2.15.0.tar.gz` |
| Speech-to-Text | Ubuntu | `ubuntu-google-cloud-speech-2.15.0.tar.gz` |
| Vertex AI Translation | Centos | `centos-google-cloud-translate-3.8.0.tar.gz` |
| Vertex AI Translation | Ubuntu | `ubuntu-google-cloud-translate-3.8.0.tar.gz` |
| Vertex AI Platform | Centos | `centos-google-cloud-aiplatform-1.34.0.tar.gz` |
| Vertex AI Platform | Ubuntu | `ubuntu-google-cloud-aiplatform-1.34.0.tar.gz` |

> [!IMPORTANT]
> **Important:** You must install the Vertex AI Platform client library to use Generative AI models like Text Embedding and Text Embedding Multilingual.

## Before you begin

Before downloading the tar file and extracting client libraries, follow these
steps:

1. [Set up a project for Vertex AI](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-set-up-project.md.txt).

2. Authenticate with gdcloud CLI:

   ```bash
   gdcloud auth login
   ```

   For more information about how to authenticate with your configured identity
   provider, see [the gdcloud CLI authentication](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-auth.md.txt).
3. Verify that you have installed Python 3.7 to 3.10. The client library
   tarballs contain wheels for `cp37` to `cp310`.

## Install a client library

After completing the [prerequisites](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-install-libraries.md.txt#before-you-begin), follow these steps to
download the tar file, and use the tar file to install a client library:

1. Download the client library you want to install:

   ```bash
   wget https://GDC_URL/.well-known/static/client-libraries/CLIENT_LIBRARY
   ```

   Replace the following:
   - `GDC_URL`: the URL of GDC Console for your organization.
   - `CLIENT_LIBRARY`: the filename of the [client library](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-install-libraries.md.txt#clientlib) you want to download.
2. Extract the library file:

   ```bash
   tar -zxf CLIENT_LIBRARY
   ```

   Extracting `OS-google-cloud-SERVICE-VERSION.tar.gz`
   (for example, `centos-google-cloud-speech-2.15.0.tar.gz`) creates the
   `LIBRARY_NAME` directory (for example,
   `google-cloud-speech`, without the `OS-` prefix or
   `-VERSION` suffix).
3. Install the client library in Distributed Cloud:

   ```bash
   pip install -r LIBRARY_NAME/requirements.txt --no-index --find-links LIBRARY_NAME
   ```

   Replace `LIBRARY_NAME` with the extracted library
   directory name, such as `google-cloud-speech`.
4. If you installed the Speech-to-Text client library, verify the installation
   and version (`2.15.0`):

   > [!NOTE]
   > **Note:** Speech-to-Text API calls on Distributed Cloud must import `from google.cloud import speech_v1p1beta1 as speech` because the API gateway routes the `google.cloud.speech.v1p1beta1.Speech` service. Importing `from google.cloud import speech` defaults to `speech_v1`, and API calls with `speech_v1` return `501 MethodNotImplemented`.

   ```python
   from google.cloud import speech_v1p1beta1 as speech

   print(speech.__version__)
   ```

   The output displays the installed version:

       2.15.0

5. Import the client library using a Python script. The following example shows
   a code snippet of a Python script that imports the Vertex AI Translation
   client library to illustrate what importing libraries looks like:

   ```python
   from google.cloud import translate
   from google.api_core.client_options import ClientOptions
   import google.auth
   from google.auth.transport import requests

   creds, _ = google.auth.default()
   creds = creds.with_gdch_audience("https://ENDPOINT:443")
   creds.refresh(requests.Request())
   client = translate.TranslationServiceClient(
       credentials=creds, client_options=ClientOptions(api_endpoint="ENDPOINT:443"))
   response = client.translate_text(request={
       "parent": "projects/PROJECT_ID", "target_language_code": "ru",
       "mime_type": "text/plain", "contents": ["Hello"]})
   print(response.translations[0].translated_text)
   ```

   Replace the following:
   - `ENDPOINT`: the Vertex AI Translation endpoint that you use for your organization, without the `https://` prefix or `:443` port. For more information, [view service status and endpoints](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt).
   - `PROJECT_ID`: your project ID.

   For more information about making Vertex AI Translation requests,
   [learn about translation features](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-translation.md.txt)
   or [translate text](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/quickstart-translation.md.txt).

   > [!NOTE]
   > **Note:** The `google-cloud-translate` 3.8.0 client library doesn't expose the `s3_source` field, so it can't create glossaries or translate documents from storage buckets. Instead, use the REST API to [create a glossary](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-glossary.md.txt#create-glossary) or [translate documents from a bucket](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-translate-docs.md.txt#translate-bucket).

6. Save the Python script with a name, such as `translation-service.py`.

7. Run the Python script:

   ```python
   python SCRIPT_NAME
   ```

   Replace `SCRIPT_NAME` with the name you gave to your
   Python script, such as `translation-service.py`.