使用 Google/Gemini 生成结构化输出，含 Instructor 的完整指南

本指南将向您展示如何将 Instructor 与 Google.GenerativeAI 库一起使用。我们推荐大多数用户使用此库，因为它更容易上手。

Google.GenerativeAI

Google 的 Gemini 模型提供强大的 AI 能力，并支持多模态。本指南将向您展示如何将 Instructor 与 Google 的 Gemini 模型结合使用，以实现类型安全、经过验证的响应。

pip install "instructor[google-generativeai, vertexai]"

简单用户示例 (同步)

import instructor
import google.generativeai as genai
from pydantic import BaseModel


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


client = instructor.from_gemini(
    client=genai.GenerativeModel(
        model_name="models/gemini-1.5-flash-latest",
    ),
    mode=instructor.Mode.GEMINI_JSON,
)

# note that client.chat.completions.create will also work
resp = client.messages.create(
    messages=[
        {
            "role": "user",
            "content": "Extract Jason is 25 years old.",
        }
    ],
    response_model=User,
)

print(resp)

简单用户示例 (异步)

异步支持

Instructor 支持 Google.GenerativeAI 库的异步模式。如果您使用的是异步客户端，请确保您的客户端与调用它的函数在同一事件循环中声明。否则您会遇到很多错误。

import instructor
import google.generativeai as genai
from pydantic import BaseModel
import asyncio


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


async def extract_user():
    client = instructor.from_gemini(
        client=genai.GenerativeModel(
            model_name="models/gemini-1.5-flash-latest",
        ),
        use_async=True,
    )

    user = await client.chat.completions.create(
        messages=[
            {
                "role": "user",
                "content": "Extract Jason is 25 years old.",
            }
        ],
        response_model=User,
    )
    return user


# Run async function
user = asyncio.run(extract_user())
print(user)  # User(name='Jason', age=25)

配置选项

您可以使用生成配置参数自定义模型的行为。这些参数控制温度、token 限制和采样方法等方面。在创建响应时，将这些参数以字典形式传递给 generation_config 参数。

最常用的参数包括： - temperature：控制输出的随机性（0.0 到 1.0） - max_tokens：要生成的最大 token 数 - top_p：核心采样参数 - top_k：考虑的最高概率 token 数

有关配置选项的更多详细信息，请参阅Google 关于 Gemini 配置参数的文档。

import instructor
import google.generativeai as genai
from pydantic import BaseModel


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


client = instructor.from_gemini(
    client=genai.GenerativeModel(
        model_name="models/gemini-1.5-flash-latest",
    ),
    mode=instructor.Mode.GEMINI_JSON,
)

# note that client.chat.completions.create will also work
resp = client.messages.create(
    messages=[
        {
            "role": "user",
            "content": "Extract Jason is 25 years old.",
        },
    ],
    response_model=User,
    generation_config={
        "temperature": 0.5,
        "max_tokens": 1000,
        "top_p": 1,
        "top_k": 32,
    },
)

print(resp)

嵌套示例

import instructor
import google.generativeai as genai
from pydantic import BaseModel


class Address(BaseModel):
    street: str
    city: str
    country: str


class User(BaseModel):
    name: str
    age: int
    addresses: list[Address]


client = instructor.from_gemini(
    client=genai.GenerativeModel(
        model_name="models/gemini-1.5-flash-latest",
    ),
)

user = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": """
            Extract: Jason is 25 years old.
            He lives at 123 Main St, New York, USA
            and has a summer house at 456 Beach Rd, Miami, USA
        """,
        },
    ],
    response_model=User,
)

print(user)
#> {
#>     'name': 'Jason',
#>     'age': 25,
#>     'addresses': [
#>         {
#>             'street': '123 Main St',
#>             'city': 'New York',
#>             'country': 'USA'
#>         },
#>         {
#>             'street': '456 Beach Rd',
#>             'city': 'Miami',
#>             'country': 'USA'
#>         }
#>     ]
#> }

流式传输支持

Instructor 提供了两种主要的流式输出响应方式

1. 迭代器 (Iterables)：当您想流式传输同一类型对象列表时非常有用（例如，使用结构化输出提取多个用户）
2. 部分流式传输 (Partial Streaming)：当您想流式传输单个对象并希望在响应传入时立即开始处理时非常有用。

部分结果

import instructor
import google.generativeai as genai
from pydantic import BaseModel


client = instructor.from_gemini(
    client=genai.GenerativeModel(
        model_name="models/gemini-1.5-flash-latest",
    ),
)


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


user = client.chat.completions.create_partial(
    messages=[
        {
            "role": "user",
            "content": "Create a user profile for Jason and 1 sentence bio, age 25",
        },
    ],
    response_model=User,
)

for user_partial in user:
    print(user_partial)
    # > name=None age=None bio=None
    # > name=None age=25 bio='Jason is a great guy'
    # > name='Jason' age=25 bio='Jason is a great guy'

迭代器示例

import instructor
import google.generativeai as genai
from pydantic import BaseModel


client = instructor.from_gemini(
    client=genai.GenerativeModel(
        model_name="models/gemini-1.5-flash-latest",
    ),
)


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


# Extract multiple users from text
users = client.chat.completions.create_iterable(
    messages=[
        {
            "role": "user",
            "content": """
            Extract users:
            1. Jason is 25 years old
            2. Sarah is 30 years old
            3. Mike is 28 years old
        """,
        },
    ],
    response_model=User,
)

for user in users:
    print(user)
    #> name='Jason' age=25
    #> name='Sarah' age=30
    #> name='Mike' age=28

Instructor 模式

我们提供了几种模式，以便轻松使用 Gemini 支持的不同响应模型

1. instructor.Mode.GEMINI_JSON ：这将原始文本补全解析为 pydantic 对象
2. instructor.Mode.GEMINI_TOOLS ：这使用 Gemini 的工具调用 API 向客户端返回结构化输出

可用模型

Google 提供了几种 Gemini 模型

• Gemini Flash (通用)
• Gemini Pro (多模态)
• Gemini Flash-8b (即将推出)

使用 Gemini 的多模态能力

我们撰写了大量关于如何将 Gemini 的多模态能力与 Instructor 结合使用的指南。

• 使用 Gemini 提取旅游视频推荐
• 使用 Gemini 解析 PDF
• 使用 Gemini 生成引文

请继续关注博客，获取更多关于使用 Gemini 与 Instructor 的指南。

相关资源

• Google AI 文档
• Instructor 核心概念
• 类型验证指南
• 高级使用示例

更新与兼容性

Instructor 保持与 Google 最新 API 版本的兼容性。请查看更新日志获取更新信息。