导师：结构化的大型语言模型输出

Instructor是一个Python库，使处理大型语言模型(LLMs)的结构化输出变得轻而易举。它构建于Pydantic之上，提供了一个简单、透明且用户友好的API，用于管理验证、重试和流式响应。准备好为您的LLM工作流加速吧！

想要您的公司徽标出现在我们的网站上吗？

如果您的公司大量使用Instructor，我们很乐意将您的徽标展示在我们的网站上！请填写这个表格

主要功能

响应模型：指定Pydantic模型以定义您的LLM输出结构
重试管理：轻松配置请求的重试次数
验证：使用Pydantic验证确保LLM响应符合您的预期
流支持：轻松处理列表和部分响应
灵活的后端：无缝集成各种LLM提供商，不仅限于OpenAI
支持多种语言：我们支持包括Python、TypeScript、Ruby、Go和Elixir在内的多种语言

几分钟内开始使用

只需一个命令即可安装Instructor：

pip install -U instructor

现在，让我们通过一个简单的示例来看一下Instructor的实际应用：

import instructor
from pydantic import BaseModel
from openai import OpenAI


# 定义所需的输出结构
class UserInfo(BaseModel):
    name: str
    age: int


# 修补OpenAI客户端
client = instructor.from_openai(OpenAI())

# 从自然语言中提取结构化数据
user_info = client.chat.completions.create(
    model="gpt-3.5-turbo",
    response_model=UserInfo,
    messages=[{"role": "user", "content": "John Doe is 30 years old."}],
)

print(user_info.name)
#> John Doe
print(user_info.age)
#> 30

使用Anthropic模型

import instructor
from anthropic import Anthropic
from pydantic import BaseModel


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


client = instructor.from_anthropic(Anthropic())

# 注意client.chat.completions.create也会有效
resp = client.messages.create(
    model="claude-3-opus-20240229",
    max_tokens=1024,
    system="You are a world class AI that excels at extracting user data from a sentence",
    messages=[
        {
            "role": "user",
            "content": "Extract Jason is 25 years old.",
        }
    ],
    response_model=User,
)

assert isinstance(resp, User)
assert resp.name == "Jason"
assert resp.age == 25

使用Cohere模型

确保安装cohere并通过export CO_API_KEY=<YOUR_COHERE_API_KEY>设置您的系统环境变量。

pip install cohere

import instructor
import cohere
from pydantic import BaseModel


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


client = instructor.from_cohere(cohere.Client())

# 注意client.chat.completions.create也会有效
resp = client.chat.completions.create(
    model="command-r-plus",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract Jason is 25 years old.",
        }
    ],
    response_model=User,
)

assert isinstance(resp, User)
assert resp.name == "Jason"
assert resp.age == 25

使用Gemini模型

确保您已安装Google AI Python SDK。您应使用API密钥设置GOOGLE_API_KEY环境变量。

pip install google-generativeai

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


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


# genai.configure(api_key=os.environ["API_KEY"]) # 备用API密钥配置
client = instructor.from_gemini(
    client=genai.GenerativeModel(
        model_name="models/gemini-1.5-flash-latest",  # 默认模型为"gemini-pro"
    ),
    mode=instructor.Mode.GEMINI_JSON,
)

或者，您可以通过OpenAI客户端调用Gemini。您需要设置gcloud，在Vertex AI上进行设置，并安装Google Auth库。

pip install google-auth

import google.auth
import google.auth.transport.requests
import instructor
from openai import OpenAI
from pydantic import BaseModel

creds, project = google.auth.default()
auth_req = google.auth.transport.requests.Request()
creds.refresh(auth_req)

# 将Vertex端点和身份验证传递给OpenAI SDK
PROJECT = 'PROJECT_ID'
LOCATION = (
    'LOCATION'  # https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations
)
base_url = f'https://{LOCATION}-aiplatform.googleapis.com/v1beta1/projects/{PROJECT}/locations/{LOCATION}/endpoints/openapi'

client = instructor.from_openai(
    OpenAI(base_url=base_url, api_key=creds.token), mode=instructor.Mode.JSON
)


# JSON模式是必须的
class User(BaseModel):
    name: str
    age: int


resp = client.chat.completions.create(
    model="google/gemini-1.5-flash-001",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract Jason is 25 years old.",
        }
    ],
    response_model=User,
)

assert isinstance(resp, User)
assert resp.name == "Jason"
assert resp.age == 25

使用Litellm

import instructor
from litellm import completion
from pydantic import BaseModel


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


client = instructor.from_litellm(completion)

resp = client.chat.completions.create(
    model="claude-3-opus-20240229",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract Jason is 25 years old.",
        }
    ],
    response_model=User,
)

assert isinstance(resp, User)
assert resp.name == "Jason"
assert resp.age == 25

类型推断正确

这曾是Instructor的梦想，但由于OpenAI的修补，我无法让类型正常工作。现在，使用新客户端，我们可以让类型正常工作了！我们还添加了一些create_*方法，使创建迭代器和部分项以及访问原始完成项变得更容易。

调用`create`

import openai
import instructor
from pydantic import BaseModel


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


client = instructor.from_openai(openai.OpenAI())

源代码如下：

user = client.chat.completions.create(
    model="gpt-4-turbo-preview",
    messages=[
        {"role": "user", "content": "Create a user"},
    ],
    response_model=User,
)

现在，如果你使用IDE，你可以看到类型被正确地推断出来。

type

处理异步：`await create`

这也可以与异步客户端正确配合使用。

import openai
import instructor
from pydantic import BaseModel


client = instructor.from_openai(openai.AsyncOpenAI())


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


async def extract():
    return await client.chat.completions.create(
        model="gpt-4-turbo-preview",
        messages=[
            {"role": "user", "content": "Create a user"},
        ],
        response_model=User,
    )

注意，因为我们返回了create方法，所以extract()函数将返回正确的用户类型。

async

返回原始的完成对象：`create_with_completion`

你也可以返回原始的完成对象。

import openai
import instructor
from pydantic import BaseModel


client = instructor.from_openai(openai.OpenAI())


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


user, completion = client.chat.completions.create_with_completion(
    model="gpt-4-turbo-preview",
    messages=[
        {"role": "user", "content": "Create a user"},
    ],
    response_model=User,
)

with_completion

流式传输部分对象：`create_partial`

为了处理流，我们仍然支持Iterable[T]和Partial[T]，但为了简化类型推断，我们还增加了create_iterable和create_partial方法！

import openai
import instructor
from pydantic import BaseModel


client = instructor.from_openai(openai.OpenAI())


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


user_stream = client.chat.completions.create_partial(
    model="gpt-4-turbo-preview",
    messages=[
        {"role": "user", "content": "Create a user"},
    ],
    response_model=User,
)

for user in user_stream:
    print(user)
    #> name=None age=None
    #> name=None age=None
    #> name=None age=None
    #> name=None age=None
    #> name=None age=None
    #> name=None age=None
    #> name='John Doe' age=None
    #> name='John Doe' age=None
    #> name='John Doe' age=None
    #> name='John Doe' age=30
    #> name='John Doe' age=30
    # name=None age=None
    # name='' age=None
    # name='John' age=None
    # name='John Doe' age=None
    # name='John Doe' age=30

现在注意到，推断出的类型是Generator[User, None]

generator

流式迭代器：`create_iterable`

当我们想要提取多个对象时，我们会得到一个对象的可迭代器。

import openai
import instructor
from pydantic import BaseModel


client = instructor.from_openai(openai.OpenAI())


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


users = client.chat.completions.create_iterable(
    model="gpt-4-turbo-preview",
    messages=[
        {"role": "user", "content": "Create 2 users"},
    ],
    response_model=User,
)

for user in users:
    print(user)
    #> name='John Doe' age=30
    #> name='Jane Doe' age=28
    # User(name='John Doe', age=30)
    # User(name='Jane Smith', age=25)

iterable

Evals

我们邀请您贡献在pytest中的evals，用以监控OpenAI模型和instructor库的质量。要开始使用，请查看anthropic和OpenAI的evals，并以pytest测试的形式贡献您自己的evals。这些evals将每周运行一次，并公布结果。

贡献

如果你想帮助，请查看一些标记为good-first-issue或help-wanted的问题。它们可能包括代码改进、客座博客文章或新食谱。

命令行界面 (CLI)

我们还提供了一些额外的CLI功能，方便使用：

instructor jobs ：帮助创建OpenAI的微调任务。简单地使用instructor jobs create-from-file --help开始创建您的第一个微调的GPT3.5模型。
instructor files ：轻松管理您上传的文件。您可以从命令行创建、删除和上传文件。
instructor usage ：您可以直接从CLI监控您的使用情况并按日期和时间段进行过滤，而无需每次都访问OpenAI网站。请注意，使用数据通常需要约5-10分钟才能从OpenAI更新。

许可证

本项目依据MIT许可证授权。

贡献者

<a href="https://github.com/jxnl/instructor/graphs/contributors"> <img src="https://contrib.rocks/image?repo=jxnl/instructor" /> </a>