Skip to content

fix(docs): correct Vertex AI migration, update Known Limitations, clarify Google providers #2343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
junqigif wants to merge 1 commit into from
+64 −38
Closed

fix(docs): correct Vertex AI migration, update Known Limitations, clarify Google providers #2343

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 32 additions & 12 deletions docs/integrations/google.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,15 @@ Master structured data extraction using Google's Gemini models with Instructor.

## Google GenAI SDK

Google's GenAI SDK is the recommended way to access Gemini models. It provides a unified interface for both the Gemini API and Vertex AI. This guide shows you how to use Instructor with Google's GenAI SDK for type-safe, validated responses.
Google's GenAI SDK (`google-genai`) is the recommended way to access Gemini models. It provides a unified interface for both the Gemini API and Vertex AI. This guide shows you how to use Instructor with Google's GenAI SDK for type-safe, validated responses.

!!! info "Choosing the right provider prefix"

Instructor supports three Google provider prefixes in `from_provider`, but only one is current:

- **`google/<model>`** (recommended): Uses the modern `google-genai` SDK. Use this for both the Gemini API and Vertex AI (add `vertexai=True` for Vertex AI).
- **`vertexai/<model>`** (deprecated): Uses the old Vertex AI SDK directly. Migrate to `google/<model>` with `vertexai=True`.
- **`gemini/<model>`** (legacy): Uses the older `google-generativeai` package. Migrate to `google/<model>`.

```bash
pip install "instructor[google-genai]"
Expand Down Expand Up @@ -321,15 +329,14 @@ for user in users:
#> name='Mike' age=28
```

## Known Limitations (as of Nov 12, 2024)
## Known Limitations (as of Jun 2026)

Google Gemini has the following known limitations when used with Instructor:

1. **Union Types**: Gemini does not support Union types (except for Optional). Use separate response models or Literal types instead.
2. **Enum Types**: Gemini returns string values instead of properly typed Enum instances. You may need to manually convert strings to enums after extraction.
3. **Union Streaming**: Streaming is not supported for Union types with Iterable.
1. **Union Types**: Gemini does not officially support Union types in structured output mode. However, Optional types (e.g., `str | None`) work correctly.
2. **Streaming**: Streaming is not supported with `Mode.TOOLS` for regular models (see the [Streaming Support](#streaming-support) section for workarounds).

These limitations are specific to Google Gemini and do not affect other providers like OpenAI or Anthropic. Tests automatically skip these features for Google to prevent failures.
These limitations are specific to Google Gemini and do not affect other providers like OpenAI or Anthropic.

## Instructor Modes

Expand Down Expand Up @@ -405,6 +412,17 @@ For Vertex AI users, the migration is similar:

#### Old Way (Deprecated)
```python
# Using the deprecated Vertex AI provider prefix
import instructor

client = instructor.from_provider(
"vertexai/gemini-2.5-flash",
mode=instructor.Mode.TOOLS,
)
```

Or using the old Vertex AI SDK directly:
```python
import instructor
import vertexai
from vertexai.generative_models import GenerativeModel
Expand All @@ -419,22 +437,24 @@ client = instructor.from_provider("google/gemini-2.5-flash", vertexai=True),
```python
import instructor

# Option 1: Using from_provider (recommended)
# Option 1: Using from_provider with vertexai=True (recommended)
client = instructor.from_provider(
"vertexai/gemini-3-flash",
project="your-project",
location="us-central1"
"google/gemini-3-flash",
vertexai=True,
project="your-project", # Optional if set in environment
location="us-central1" # Optional, defaults to us-central1
)

# Option 2: Using from_genai with vertexai=True (legacy/advanced)
# Option 2: Using from_genai with Google GenAI SDK
from google import genai
from instructor import from_genai

client = from_genai(
genai.Client(
vertexai=True,
project="your-project",
location="us-central1"
location="us-central1",
model="gemini-3-flash"
)
)
```
Expand Down
58 changes: 32 additions & 26 deletions docs/integrations/vertex.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@ class User(BaseModel):

# Using from_provider (recommended)
client = instructor.from_provider(
"vertexai/gemini-3-flash",
"google/gemini-3-flash",
vertexai=True,
)

resp = client.create(
Expand All @@ -61,22 +62,18 @@ print(resp)
```python
import asyncio
import instructor
import vertexai # type: ignore
from vertexai.generative_models import GenerativeModel # type: ignore
from pydantic import BaseModel

vertexai.init()


class User(BaseModel):
name: str
age: int


client = instructor.from_provider(
"vertex_ai/gemini-1.5-pro-preview-0409",
"google/gemini-3-flash",
vertexai=True,
async_client=True,
mode=instructor.Mode.TOOLS,
)

async def extract_user():
Expand Down Expand Up @@ -104,21 +101,19 @@ Instructor now supports streaming capabilities with Vertex AI! You can use both
### Streaming Partial Responses

```python
import vertexai # type: ignore
from vertexai.generative_models import GenerativeModel # type: ignore
import instructor
from pydantic import BaseModel
from instructor.dsl.partial import Partial

vertexai.init()

class UserExtract(BaseModel):
name: str
age: int


client = instructor.from_provider(
"vertex_ai/gemini-1.5-pro-preview-0409",
mode=instructor.Mode.TOOLS,
"google/gemini-3-flash",
vertexai=True,
)

# Stream partial responses
Expand All @@ -140,20 +135,18 @@ for partial_user in response_stream:
### Streaming Iterable Collections

```python
import vertexai # type: ignore
from vertexai.generative_models import GenerativeModel # type: ignore
import instructor
from pydantic import BaseModel

vertexai.init()

class UserExtract(BaseModel):
name: str
age: int


client = instructor.from_provider(
"vertex_ai/gemini-1.5-pro-preview-0409",
mode=instructor.Mode.TOOLS,
"google/gemini-3-flash",
vertexai=True,
)

# Stream iterable responses
Expand All @@ -177,22 +170,20 @@ You can also use async versions of both streaming approaches:

```python
import asyncio
import vertexai # type: ignore
from vertexai.generative_models import GenerativeModel # type: ignore
import instructor
from pydantic import BaseModel
from instructor.dsl.partial import Partial

vertexai.init()

class UserExtract(BaseModel):
name: str
age: int


client = instructor.from_provider(
"vertex_ai/gemini-1.5-pro-preview-0409",
"google/gemini-3-flash",
vertexai=True,
async_client=True,
mode=instructor.Mode.TOOLS,
)

async def stream_partial():
Expand Down Expand Up @@ -232,17 +223,31 @@ asyncio.run(stream_iterable())

## Migration to Google GenAI

The legacy `from_vertexai` method is being deprecated in favor of the unified Google GenAI SDK. Here's how to migrate:
The legacy `from_vertexai` method and the `vertexai/` provider prefix are deprecated in favor of the unified Google GenAI SDK with `vertexai=True`. Here's how to migrate:

### Old Way (Deprecated)
```python
# Using the deprecated vertexai/ provider prefix
import instructor

client = instructor.from_provider(
"vertexai/gemini-2.5-flash",
project="your-project",
location="us-central1"
)
```

Or using the old Vertex AI SDK directly:
```python
import instructor
import vertexai
from vertexai.generative_models import GenerativeModel

vertexai.init(project="your-project", location="us-central1")

client = instructor.from_provider("google/gemini-2.5-flash", vertexai=True),
client = instructor.from_provider(
"google/gemini-2.5-flash",
vertexai=True,
mode=instructor.Mode.TOOLS,
)
```
Expand All @@ -251,9 +256,10 @@ client = instructor.from_provider("google/gemini-2.5-flash", vertexai=True),
```python
import instructor

# Option 1: Using from_provider (simplest)
# Option 1: Using from_provider with vertexai=True (simplest)
client = instructor.from_provider(
"vertexai/gemini-3-flash",
"google/gemini-3-flash",
vertexai=True,
project="your-project", # Optional if set in environment
location="us-central1" # Optional, defaults to us-central1
)
Expand Down