feat: add vertex ai skills to repo (#4454)

Author: vincentkt-google

README.md

@@ -45,7 +45,7 @@ To get started using Vertex AI, you must have a Google Cloud project.
 │   │   ├── model_garden
 │   │   ├── ...
 ├── community-content - Sample code and tutorials contributed by the community
-
+├─- skills - Skills related to Vertex AI interaction
 ```
 ## Examples
 

skills/vertex-tuning/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: vertex-tuning
+description: >
+  Vertex AI Model Tuning. Use when you need to fine-tune models
+  using Vertex AI's infrastructure.
+---
+
+# Vertex AI Model Tuning
+
+## Overview
+
+This skill provides procedural knowledge for fine-tuning Large Language Models
+(LLMs) using Vertex AI's tuning service. It covers the entire lifecycle from
+environment setup and data preparation to job configuration, monitoring, and
+deployment.
+
+## Workflow Decision Tree
+
+1.  **Environment Check**: Has the environment (Auth, APIs, IAM, Venv) been
+    initialized?
+
+    -   **No** → Go to [Phase 0: Environment & IAM Setup](#phase-0).
+    -   **Yes** → Proceed.
+
+2.  **Dataset Status**: Is the dataset ready in JSONL format and uploaded to
+    GCS?
+
+    -   **No** → Go to [Phase 1: Dataset Preparation & Upload](#phase-1).
+    -   **Yes** → Proceed.
+
+3.  **Configuration**: Have the target model and hyperparameters been decided?
+
+    -   **No** → Go to [Phase 2: Recommendations & Configuration](#phase-2).
+    -   **Yes** → Proceed.
+
+4.  **Job Status**: Has the tuning job been submitted?
+
+    -   **No** → Go to
+        [Phase 3: Tuning Job Execution](#phase-3-tuning-job-execution).
+    -   **Yes** → Proceed.
+
+5.  **Job Completion**: Is the tuning job complete?
+
+    -   **No** → Go to [Phase 4: Monitoring](#phase-4-monitoring).
+    -   **Yes** → Proceed.
+
+6.  **Deployment**: Has the tuned model been deployed to an endpoint?
+
+    -   **No** → Go to [Phase 5: Model Deployment](#phase-5-model-deployment).
+    -   **Yes** → Task Complete.
+
+--------------------------------------------------------------------------------
+
+## Phase 0: Environment & IAM Setup {#phase-0}
+
+Ensure the foundational environment is ready before proceeding.
+
+### 0.1 Authentication & Project Context
+
+-   Check if `gcloud` CLI is installed. If it is not installed, prompt the user
+    for permission to install it before proceeding.
+-   Verify `gcloud auth list`. If not authenticated, run `gcloud auth login`.
+-   Ensure `project` and `location` are known. Use `gcloud config get project`
+    to retrieve the current project (and `gcloud config get compute/region` for
+    region).
+-   **CRITICAL: Ask for Confirmation.** You must prompt the user to confirm the
+    retrieved project and region before proceeding, in case they want to switch
+    to a different one.
+
+### 0.2 Enable APIs
+
+Ensure `aiplatform.googleapis.com` and `storage.googleapis.com` are enabled.
+`bash gcloud services enable aiplatform.googleapis.com storage.googleapis.com
+--project=YOUR_PROJECT`
+
+### 0.3 IAM Permissions
+
+Verify the following identities have the required roles.
+
+-   **Vertex AI Service Agent**:
+    `service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com`
+-   **Managed OSS Fine Tuning Service Agent**:
+    `service-PROJECT_NUMBER@gcp-sa-vertex-moss-ft.iam.gserviceaccount.com`
+-   **User Identity**: The account running the commands.
+
+### 0.4 Virtual Environment
+
+Create and use a virtual environment named `tuning_agent_venv` in the home
+directory. Install dependencies from `references/requirements.txt`. `bash
+python3 -m venv ~/tuning_agent_venv source ~/tuning_agent_venv/bin/activate pip
+install -r references/requirements.txt`
+
+--------------------------------------------------------------------------------
+
+## Phase 1: Dataset Preparation & Upload {#phase-1}
+
+Vertex AI requires valid JSONL format in GCS.
+
+### 1.0 Dataset Discovery & Confirmation
+
+-   **Ask the User First:** Ask the user if they already have a dataset they
+    want to use.
+-   **Auto-Discovery:** If the user does not have a dataset, search the
+    authenticated project's GCS buckets to find if any existing file has a
+    reasonable dataset that can do the job the user prompted initially.
+-   **CRITICAL: Ask for Confirmation.** Do not proceed with dataset preparation
+    or upload until you present the found or provided dataset to the user and
+    they confirm the dataset to use.
+
+### 1.1 Formatting & Validation
+
+-   **Conversion**: If data is in CSV or JSON, use `vertex-tuning/scripts/prepare_dataset.py`
+    to convert.
+-   **Validation Split Confirmation**: If the user only provides a training
+    dataset, **you must prompt the user** to seek permission to split the
+    training dataset 80/20 to form a validation dataset (using
+    `--validation_split 0.2`). If they agree, proceed with the split. If they
+    decline, just use the training dataset without a validation dataset.
+-   **Validation**: If data is already in JSONL, validate it before uploading:
+    `bash python3 vertex-tuning/scripts/prepare_dataset.py
+    \ --input my_data.jsonl \ --format messages \ --validate_only`
+-   Refer to [Data Preparation Guide](references/data_prep.md) for required
+    schemas.
+
+### 1.2 Upload
+
+Upload formatted `.jsonl` files to GCS using a unique directory (e.g., with a
+datetime timestamp) to avoid overwriting outputs from different runs.
+
+```bash
+gcloud storage cp dataset.jsonl gs://YOUR_BUCKET/tuning_agent_job_<datetime>/dataset.jsonl
+```
+
+--------------------------------------------------------------------------------
+
+## Phase 2: Recommendations & Configuration {#phase-2}
+
+Help the user choose the best model and parameters. **Always seek user
+confirmation before submitting the job.**
+
+### 2.1 Model Selection
+
+-   If the user does not specify a model in their prompt, recommend a model
+    based on the user's prompt by referencing the
+    [Models Catalog](references/models.md).
+-   **Prompt for Confirmation:** Present the recommended model to the user and
+    ask for their confirmation.
+
+### 2.2 Hyperparameters
+
+-   If the user does not specify hyperparameters, recommend `tuning_mode`,
+    `epochs`, `learning_rate`, and `adapter_size` based on the
+    [Tuning Guide](references/tuning_guide.md) and model-specific baselines in
+    the [Models Catalog](references/models.md).
+-   **Prompt for Confirmation:** Present the recommended hyperparameter
+    configuration to the user and ask for their approval before proceeding to
+    job submission.
+
+--------------------------------------------------------------------------------
+
+## Phase 3: Tuning Job Execution
+
+Submit the job using `scripts/tune_model.py`.
+
+```bash
+python3 scripts/tune_model.py \
+    --project YOUR_PROJECT \
+    --location YOUR_LOCATION \
+    --bucket YOUR_STAGING_BUCKET \
+    --base_model BASE_MODEL_ID \
+    --train_dataset gs://YOUR_BUCKET/tuning_agent_job_<datetime>/dataset.jsonl \
+    --output_uri gs://YOUR_BUCKET/tuning_agent_job_<datetime>/output \
+    --epochs EPOCHS \
+    --learning_rate LR \
+    --tuning_mode MODE
+```
+
+--------------------------------------------------------------------------------
+
+## Phase 4: Monitoring
+
+Monitor the job via the Cloud Console link provided in the script output or by
+polling the job status.
+
+--------------------------------------------------------------------------------
+
+## Phase 5: Model Deployment
+
+Once the job is `SUCCEEDED`, deploy the model using `scripts/deploy_model.py`.
+
+```bash
+python3 vertex_tuning/scripts/deploy_model.py \
+    --project YOUR_PROJECT \
+    --location YOUR_LOCATION \
+    --artifacts_uri gs://YOUR_BUCKET/tuning_agent_job_<datetime>/output/postprocess/node-0/checkpoints/final \
+    --machine_type MACHINE_TYPE \
+    --accelerator_type ACCELERATOR_TYPE \
+    --accelerator_count COUNT
+```
+
+Refer to [Models Catalog](references/models.md) for hardware recommendations.
+
+--------------------------------------------------------------------------------
+
+## Resources
+
+-   [Data Preparation Guide](references/data_prep.md)
+-   [Models Catalog](references/models.md)
+-   [Tuning Guide](references/tuning_guide.md)
+-   `scripts/prepare_dataset.py`: Data conversion & validation.
+-   `scripts/tune_model.py`: Job submission.
+-   `scripts/deploy_model.py`: Model deployment.

skills/vertex-tuning/references/data_formatting.md

@@ -0,0 +1,71 @@
+# Data Formatting for Vertex AI Model Tuning
+
+Vertex AI Model Tuning requires training data in **JSON Lines (JSONL)**
+format. Each line must be a valid JSON object representing a single training
+example.
+
+## Supported Formats
+
+### 1. Conversational (Messages) Format
+Recommended for chat-based models (Llama 3 Chat, Gemma IT, etc.).
+
+```json
+{
+  "messages": [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "What is the capital of France?"},
+    {"role": "assistant", "content": "The capital of France is Paris."}
+  ]
+}
+```
+
+### 2. Instruction (Prompt/Completion) Format
+Suitable for base models or simple completion tasks.
+
+```json
+{
+  "prompt": "Summarize the following text: [TEXT]",
+  "completion": "[SUMMARY]"
+}
+```
+
+## Dataset Requirements
+
+- **File Type**: `.jsonl`
+- **Location**: Must be uploaded to a Google Cloud Storage (GCS) bucket.
+- **Validation Split**: If provided, it must be less than 5,000 rows AND less than 25% of the training dataset size.
+- **Encoding**: UTF-8.
+
+## Sequence Length Limitations
+
+Each model has a maximum sequence length (context window) supported during
+tuning. Examples exceeding this limit may be truncated.
+
+Please refer to the [official documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/open-model-tuning)
+for the latest maximum sequence length limits for specific models and tuning
+modes.
+
+*Note: As a rule of thumb, 1 token is approximately 4 characters of
+English text.*
+
+## Bucket Considerations
+
+If the user has not provided a bucket name create one using the following
+command with the location same as the tuning job location.
+
+```bash
+gcloud storage buckets create gs://vertex-tuning-agent --location=BUCKET_LOCATION
+```
+
+## Preparation Workflow
+
+1. **Collect Data**: Gather your raw data in CSV, JSONL, Parquet, or from
+   Hugging Face.
+2. **Apply Template**: Format each example using a template appropriate for
+   your target model (e.g., Llama 3 prompt template).
+3. **Convert to JSONL**: Save the formatted examples to a `.jsonl` file.
+4. **Upload to GCS**: Use `gcloud storage cp` to move the file to your bucket.
+
+```bash
+gcloud storage cp dataset.jsonl gs://your-bucket/path/dataset.jsonl
+```

skills/vertex-tuning/references/data_prep.md

@@ -0,0 +1,50 @@
+# Data Preparation for Vertex AI Model Tuning
+
+Vertex AI Model Tuning requires training data in **JSON Lines (JSONL)** format
+stored in Google Cloud Storage (GCS).
+
+## Supported JSONL Formats
+
+### 1. Conversational (Messages) Format
+Recommended for chat-based models (Llama 3.1/3.2/3.3 Chat, Gemma 3 IT, etc.).
+
+```json
+{
+  "messages": [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "What is the capital of France?"},
+    {"role": "assistant", "content": "The capital of France is Paris."}
+  ]
+}
+```
+
+### 2. Instruction (Prompt/Completion) Format
+Suitable for base models or simple completion tasks.
+
+```json
+{
+  "prompt": "Summarize the following text: [TEXT]",
+  "completion": "[SUMMARY]"
+}
+```
+
+## Dataset Requirements
+
+- **File Type**: Must be `.jsonl`.
+- **Encoding**: UTF-8.
+- **Location**: Must be in a GCS bucket (e.g., `gs://my-bucket/train.jsonl`).
+- **Validation Split**: A separate validation file is optional but recommended. It must be no more than 25% of the training dataset size.
+
+## Bucket Considerations
+
+If a bucket does not exist, create one in the same region as your tuning job:
+
+```bash
+gcloud storage buckets create gs://YOUR_BUCKET_NAME --location=YOUR_LOCATION
+```
+
+## Formatting Best Practices
+
+1. **Quality over Quantity**: 100 high-quality examples often outperform 1,000 noisy ones.
+2. **Consistency**: Use consistent formatting for system prompts and instruction styles.
+3. **No Empty Values**: Ensure every example has a valid prompt/user message and completion/assistant response. Use the [preparation script](/cloud/ai/platform/modelgarden/agent_skills/vertex-tuning/scripts/prepare_dataset.py) to validate this.

skills/vertex-tuning/references/model_recommendation.md

@@ -0,0 +1,37 @@
+# Starting Model and Tuning Method Recommendation
+
+## Available Models
+
+- Gemma 3 27B IT (google/gemma-3-27b-it)
+- Llama 3.1 8B (meta/llama3_1@llama-3.1-8b)
+- Llama 3.1 8B Instruct (meta/llama3_1@llama-3.1-8b-instruct)
+- Llama 3.2 1B Instruct (meta/llama3-2@llama-3.2-1b-instruct)
+- Llama 3.2 3B Instruct (meta/llama3-2@llama-3.2-3b-instruct)
+- Llama 3.3 70B Instruct (meta/llama3-3@llama-3.3-70b-instruct)
+- Qwen 3 32B (qwen/qwen3@qwen3-32b)
+- Llama 4 Scout 17B 16E Instruct (meta/llama4@llama-4-scout-17b-16e-instruct)
+
+## Guidelines to follow for model Selection
+
+Different families are suitable for different types of tasks.
+
+- Qwen is a good choice for code generation or math based tasks.
+- Gemma is a good choice for chat based tasks.
+- Llama is an okay choice for other tasks.
+- Only one model in the list Llama 3.1 8B is not an instruct model, this is
+best suited for continuation tasks.
+
+Gauge the complexity of the task by examining samples from the
+dataset.
+
+Tasks that are easier should be handled by smaller models, while more complex
+tasks should be handled by larger models.
+
+For example, a task that requires simple question answering can be handles by
+the 1B or 3B models, while a task that requires complex reasoning should be
+handled by either the Qwen 3 32B, Gemma 3 27B or Llama 3.3 70B model.
+Any intermediate tasks can be handled by the 8B or 17B models.
+
+Another aspect to consider is if the dataset is multi turn or needs tool calling
+capabilities prefer the strongest models. Qwen 3 32B > Gemma 3 27B >
+Llama 3.3 70B unless the user explicitly requests otherwise.