feat: Jina EmbV3 launch (#4476)

* feat: Jina EmbV3 launch

* feat: Jina EmbV3 launch
This commit is contained in:
Sam-Deciga
2026-03-20 08:19:38 -04:00
committed by GitHub
parent 772ee71bc3
commit a1d898f35e
@@ -0,0 +1,633 @@
{
"cells": [
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "483138c1a042"
},
"outputs": [],
"source": [
"# Copyright 2026 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": "e5d761077c25"
},
"source": [
"# Getting Started with Jina Embeddings v3 on Vertex AI\n",
"\n",
"<table align=\"left\">\n",
" <td style=\"text-align: center\">\n",
" <a href=\"https://colab.research.google.com/github/GoogleCloudPlatform/vertex-ai-samples/blob/main/notebooks/official/generative_ai/notebook_jina_embeddings_v3_intro.ipynb\">\n",
" <img src=\"https://www.gstatic.com/pantheon/images/bigquery/welcome_page/colab-logo.svg\" alt=\"Google Colaboratory logo\"><br> Open in Colab\n",
" </a>\n",
" </td>\n",
" <td style=\"text-align: center\">\n",
" <a href=\"https://console.cloud.google.com/vertex-ai/colab/import/https:%2F%2Fraw.githubusercontent.com%2FGoogleCloudPlatform%2Fvertex-ai-samples%2Fmain%2Fnotebooks%2Fofficial%2Fgenerative_ai%2Fnotebook_jina_embeddings_v3_intro.ipynb\">\n",
" <img width=\"32px\" src=\"https://lh3.googleusercontent.com/JmcxdQi-qOpctIvWKgPtrzZdJJK-J3sWE1RsfjZNwshCFgE_9fULcNpuXYTilIR2hjwN\" alt=\"Google Cloud Colab Enterprise logo\"><br> Open in Colab Enterprise\n",
" </a>\n",
" </td>\n",
" <td style=\"text-align: center\">\n",
" <a href=\"https://console.cloud.google.com/vertex-ai/workbench/deploy-notebook?download_url=https://raw.githubusercontent.com/GoogleCloudPlatform/vertex-ai-samples/main/notebooks/official/generative_ai/notebook_jina_embeddings_v3_intro.ipynb\">\n",
" <img src=\"https://www.gstatic.com/images/branding/gcpiconscolors/vertexai/v1/32px.svg\" alt=\"Vertex AI logo\"><br> Open in Workbench\n",
" </a>\n",
" </td>\n",
" <td style=\"text-align: center\">\n",
" <a href=\"https://github.com/GoogleCloudPlatform/vertex-ai-samples/main/notebooks/official/generative_ai/notebook_jina_embeddings_v3_intro.ipynb\">\n",
" <img src=\"https://raw.githubusercontent.com/primer/octicons/refs/heads/main/icons/mark-github-24.svg\" alt=\"GitHub logo\"><br> View on GitHub\n",
" </a>\n",
" </td>\n",
"</table>"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "8381d89c640f"
},
"source": [
"## Overview\n",
"\n",
"This notebook demonstrates how to deploy and use **jina-embeddings-v3** from Vertex AI Model Garden.\n",
"\n",
"You will learn how to:\n",
"- Deploy jina-embeddings-v3 to a Vertex AI endpoint\n",
"- Generate text embeddings using the deployed model\n",
"- Use task-specific LoRA adapters for retrieval, classification, and clustering\n",
"- Control embedding dimensions with Matryoshka representation\n",
"- Compute cross-lingual semantic similarity\n",
"\n",
"### Jina Embeddings v3 on Vertex AI\n",
"\n",
"jina-embeddings-v3 is available as a self-deploy model on Vertex AI Model Garden. You deploy the model to your own Vertex AI endpoint on GPU hardware.\n",
"\n",
"For more information, see the [Jina AI Embedding documentation](https://jina.ai/embeddings)."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "36df818a34bd"
},
"source": [
"## Get Started"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "c832028166e3"
},
"source": [
"### Install required packages"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "030faea19be1"
},
"outputs": [],
"source": [
"! pip3 install --upgrade --quiet google-cloud-aiplatform numpy"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "848322ec177e"
},
"source": [
"### Restart runtime (Colab only)\n",
"\n",
"To use the newly installed packages, you must restart the runtime on Google Colab."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "b8d49bb74a53"
},
"outputs": [],
"source": [
"import sys\n",
"\n",
"if \"google.colab\" in sys.modules:\n",
"\n",
" import IPython\n",
"\n",
" app = IPython.Application.instance()\n",
" app.kernel.do_shutdown(True)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "215f648d2d0f"
},
"source": [
"<div class=\"alert alert-block alert-warning\">\n",
"<b>The kernel is going to restart. Wait until it's finished before continuing to the next step.</b>\n",
"</div>"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "11947ae0fe5e"
},
"source": [
"### Authenticate your notebook environment (Colab only)\n",
"\n",
"Authenticate your environment on Google Colab."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "015bf6d5da75"
},
"outputs": [],
"source": [
"import sys\n",
"\n",
"if \"google.colab\" in sys.modules:\n",
"\n",
" from google.colab import auth\n",
"\n",
" auth.authenticate_user()"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "0d09491cf7ef"
},
"source": [
"### Set Google Cloud project information and initialize Vertex AI SDK\n",
"\n",
"To get started using Vertex AI, you must have an existing Google Cloud project and [enable the Vertex AI API](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com). Learn more about [setting up a project and a development environment](https://cloud.google.com/vertex-ai/docs/start/cloud-environment)."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "78bef96a14a9"
},
"outputs": [],
"source": [
"PROJECT_ID = \"[your-project-id]\" # @param {type:\"string\"}\n",
"LOCATION = \"us-central1\" # @param [\"us-central1\", \"us-east1\", \"us-east4\", \"us-west1\", \"us-west4\", \"northamerica-northeast2\", \"europe-west1\", \"europe-west2\", \"europe-west3\", \"europe-west4\", \"europe-west6\", \"me-central2\", \"asia-east1\", \"asia-northeast1\", \"asia-northeast3\", \"asia-south1\", \"asia-southeast1\", \"asia-southeast2\"] {type:\"string\"}\n",
"\n",
"if not PROJECT_ID or PROJECT_ID == \"[your-project-id]\":\n",
" raise ValueError(\"Please set your PROJECT_ID\")\n",
"\n",
"ENDPOINT = f\"https://{LOCATION}-aiplatform.googleapis.com\"\n",
"PUBLISHER_NAME = \"jinaai\"\n",
"PUBLISHER_MODEL_NAME = \"jina-embeddings-v3\""
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "43a30006d5a9"
},
"source": [
"### Import required libraries"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "97349fce6f69"
},
"outputs": [],
"source": [
"import json\n",
"import time\n",
"\n",
"import numpy as np\n",
"from google.cloud import aiplatform"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "cca6afd44305"
},
"source": [
"## Deploy Model to Vertex AI\n",
"\n",
"The following cells upload the model from Model Garden, create an endpoint, and deploy the model."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "6a7bae4a73d4"
},
"source": [
"### Initialize Vertex AI SDK"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "14860e92ee6f"
},
"outputs": [],
"source": [
"aiplatform.init(project=PROJECT_ID, location=LOCATION)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "f51865b67259"
},
"source": [
"### Upload Model"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "982731ef16e9"
},
"outputs": [],
"source": [
"model = aiplatform.Model.upload(\n",
" display_name=\"jina-embeddings-v3-\" + time.strftime(\"%Y%m%d-%H%M%S\"),\n",
" model_garden_source_model_name=f\"publishers/{PUBLISHER_NAME}/models/{PUBLISHER_MODEL_NAME}\",\n",
")\n",
"print(f\"Model resource name: {model.resource_name}\")"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "47236a8dd5bc"
},
"source": [
"### Create Endpoint"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "376b7a9a6db2"
},
"outputs": [],
"source": [
"my_endpoint = aiplatform.Endpoint.create(\n",
" display_name=\"jina-embeddings-v3-endpoint-\" + time.strftime(\"%Y%m%d-%H%M%S\")\n",
")\n",
"print(f\"Endpoint resource name: {my_endpoint.resource_name}\")"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "73e505a696a8"
},
"source": [
"### Deploy Model\n",
"\n",
"Deploy to a `g2-standard-8` machine with a single NVIDIA L4 GPU (recommended). The 570M parameter model fits comfortably in 24 GB VRAM. Higher-end GPUs (A100, H100) are also supported for increased throughput."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "785fda5d7d70"
},
"outputs": [],
"source": [
"MACHINE_TYPE = \"g2-standard-8\" # @param [\"g2-standard-8\", \"a2-highgpu-1g\", \"a2-ultragpu-1g\", \"a3-highgpu-1g\"] {type: \"string\"}\n",
"\n",
"ACCELERATOR_MAP = {\n",
" \"g2-standard-8\": \"NVIDIA_L4\",\n",
" \"a2-highgpu-1g\": \"NVIDIA_TESLA_A100\",\n",
" \"a2-ultragpu-1g\": \"NVIDIA_A100_80GB\",\n",
" \"a3-highgpu-1g\": \"NVIDIA_H100_80GB\",\n",
"}\n",
"ACCELERATOR_TYPE = ACCELERATOR_MAP[MACHINE_TYPE]\n",
"ACCELERATOR_COUNT = 1\n",
"\n",
"print(f\"Machine type: {MACHINE_TYPE}\")\n",
"print(f\"Accelerator: {ACCELERATOR_TYPE}\")"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "5375b1cc4b18"
},
"outputs": [],
"source": [
"model.deploy(\n",
" endpoint=my_endpoint,\n",
" deployed_model_display_name=\"jina-embeddings-v3-deployed-\"\n",
" + time.strftime(\"%Y%m%d-%H%M%S\"),\n",
" traffic_split={\"0\": 100},\n",
" machine_type=MACHINE_TYPE,\n",
" accelerator_type=ACCELERATOR_TYPE,\n",
" accelerator_count=ACCELERATOR_COUNT,\n",
" min_replica_count=1,\n",
" max_replica_count=1,\n",
")\n",
"print(\"Model deployed successfully.\")"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "3cf8e82c08a1"
},
"source": [
"## Generate Embeddings\n",
"\n",
"Send embedding requests to the deployed endpoint using `raw_predict`. The request format follows the OpenAI embeddings API schema."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "e2452fd2816d"
},
"source": [
"### Helper functions"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "cb748881811a"
},
"outputs": [],
"source": [
"def get_embeddings(texts, task=\"text-matching\", dimensions=1024):\n",
" \"\"\"Get embeddings from the deployed Vertex AI endpoint.\"\"\"\n",
" payload = {\n",
" \"model\": \"jina-embeddings-v3\",\n",
" \"task\": task,\n",
" \"dimensions\": dimensions,\n",
" \"input\": texts,\n",
" }\n",
" response = my_endpoint.raw_predict(\n",
" body=json.dumps(payload),\n",
" headers={\"Content-Type\": \"application/json\"},\n",
" )\n",
" result = json.loads(response.text)\n",
" return np.array([d[\"embedding\"] for d in result[\"data\"]])\n",
"\n",
"\n",
"def cosine_similarity(a, b):\n",
" \"\"\"Compute cosine similarity between two vectors.\"\"\"\n",
" return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "4a11e1539995"
},
"source": [
"### Basic embedding request\n",
"\n",
"Generate embeddings for a list of texts using the `retrieval.query` task adapter."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "ffd745645bda"
},
"outputs": [],
"source": [
"payload = {\n",
" \"model\": \"jina-embeddings-v3\",\n",
" \"task\": \"retrieval.query\",\n",
" \"dimensions\": 1024,\n",
" \"input\": [\n",
" \"What is machine learning?\",\n",
" \"How do neural networks work?\",\n",
" ],\n",
"}\n",
"\n",
"response = my_endpoint.raw_predict(\n",
" body=json.dumps(payload),\n",
" headers={\"Content-Type\": \"application/json\"},\n",
")\n",
"result = json.loads(response.text)\n",
"\n",
"print(f\"Model: {result['model']}\")\n",
"print(f\"Number of embeddings: {len(result['data'])}\")\n",
"print(f\"Embedding dimension: {len(result['data'][0]['embedding'])}\")\n",
"print(f\"Token usage: {result['usage']}\")"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "65eeff867809"
},
"source": [
"### Task-specific LoRA adapters\n",
"\n",
"jina-embeddings-v3 includes 5 task-specific LoRA adapters. Selecting the right adapter for your use case improves embedding quality.\n",
"\n",
"| Task | Description | Use case |\n",
"|---|---|---|\n",
"| `retrieval.query` | Query embeddings for asymmetric search | Search queries |\n",
"| `retrieval.passage` | Passage embeddings for asymmetric search | Documents to be searched |\n",
"| `separation` | Optimized for clustering and re-ranking | Document clustering |\n",
"| `classification` | Optimized for classification tasks | Text categorization |\n",
"| `text-matching` | Symmetric similarity | Duplicate detection, STS |"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "6a330762098a"
},
"source": [
"### Asymmetric retrieval with query and passage adapters\n",
"\n",
"For search applications, use `retrieval.query` for queries and `retrieval.passage` for documents."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "91c7442191b7"
},
"outputs": [],
"source": [
"query = [\"What are the health benefits of green tea?\"]\n",
"\n",
"passages = [\n",
" \"Green tea contains antioxidants called catechins that may help prevent cell damage. Regular consumption has been linked to improved heart health and reduced risk of certain cancers.\",\n",
" \"Black tea is fully oxidized, giving it a stronger flavor and darker color compared to green tea. It contains more caffeine than green tea.\",\n",
" \"The process of making ceramic teapots involves shaping clay on a wheel, followed by drying and firing in a kiln at high temperatures.\",\n",
"]\n",
"\n",
"query_embedding = get_embeddings(query, task=\"retrieval.query\")\n",
"passage_embeddings = get_embeddings(passages, task=\"retrieval.passage\")\n",
"\n",
"print(\"Query:\", query[0])\n",
"print(\"\\nPassage similarities:\")\n",
"for i, passage in enumerate(passages):\n",
" sim = cosine_similarity(query_embedding[0], passage_embeddings[i])\n",
" print(f\" [{sim:.4f}] {passage[:80]}...\")"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "dc2c4845e0f7"
},
"source": [
"### Cross-lingual semantic similarity\n",
"\n",
"jina-embeddings-v3 supports 30+ trained languages. Texts with similar meaning in different languages produce similar embeddings."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "9f772872062e"
},
"outputs": [],
"source": [
"texts = [\n",
" \"The weather is beautiful today.\",\n",
" \"Das Wetter ist heute wundersch\\u00f6n.\",\n",
" \"Le temps est magnifique aujourd'hui.\",\n",
" \"\\u4eca\\u5929\\u5929\\u6c14\\u771f\\u597d\\u3002\",\n",
" \"I need to fix my bicycle.\",\n",
"]\n",
"\n",
"embeddings = get_embeddings(texts, task=\"text-matching\")\n",
"\n",
"labels = [\"EN: weather\", \"DE: weather\", \"FR: weather\", \"ZH: weather\", \"EN: bicycle\"]\n",
"\n",
"print(\"Cross-lingual similarity matrix:\")\n",
"print(f\"{'':>15}\", end=\"\")\n",
"for label in labels:\n",
" print(f\"{label:>15}\", end=\"\")\n",
"print()\n",
"\n",
"for i, label_i in enumerate(labels):\n",
" print(f\"{label_i:>15}\", end=\"\")\n",
" for j in range(len(labels)):\n",
" sim = cosine_similarity(embeddings[i], embeddings[j])\n",
" print(f\"{sim:>15.4f}\", end=\"\")\n",
" print()"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "31ccc85b1a34"
},
"source": [
"### Matryoshka embeddings: flexible dimensions\n",
"\n",
"jina-embeddings-v3 supports Matryoshka Representation Learning. You can truncate embeddings to smaller dimensions (32, 64, 128, 256, 512, 768) while retaining most of the performance."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "140b5a339f79"
},
"outputs": [],
"source": [
"text_pair = [\n",
" \"Artificial intelligence is transforming healthcare.\",\n",
" \"AI applications in medicine are growing rapidly.\",\n",
"]\n",
"\n",
"print(\"Similarity at different embedding dimensions:\")\n",
"for dim in [32, 64, 128, 256, 512, 1024]:\n",
" embs = get_embeddings(text_pair, task=\"text-matching\", dimensions=dim)\n",
" sim = cosine_similarity(embs[0], embs[1])\n",
" print(f\" dim={dim:>4}: similarity={sim:.4f}\")"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "b0f4a255312c"
},
"source": [
"## Cleaning up\n",
"\n",
"To avoid incurring charges, undeploy the model and delete the endpoint when you are done."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "094dfef1f7ac"
},
"outputs": [],
"source": [
"# Undeploy all models from the endpoint\n",
"my_endpoint.undeploy_all()\n",
"\n",
"# Delete the endpoint\n",
"my_endpoint.delete()\n",
"\n",
"# Delete the model\n",
"model.delete()\n",
"\n",
"print(\"Resources cleaned up.\")"
]
}
],
"metadata": {
"colab": {
"name": "notebook_jina_embeddings_v3_intro.ipynb",
"toc_visible": true
},
"kernelspec": {
"display_name": "Python 3",
"name": "python3"
}
},
"nbformat": 4,
"nbformat_minor": 0
}