Instructor

Weave の Instructor インテグレーションを使って LLM からの構造化データ抽出をトレースおよび評価し、Pydantic モデルの検証、リトライ ロジック、JSON スキーマ適用を記録して、信頼性の高い構造化出力ワークフローを実現します。

Instructor は、LLM から JSON のような構造化データを簡単に取得できる軽量ライブラリです。

​

トレース

言語モデルアプリケーションのトレースは、開発中と本番環境の両方で、一元的な場所に保存・管理しておくことが重要です。これらのトレースはデバッグに役立つだけでなく、アプリケーションの改善に役立つデータセットとしても利用できます。

Weave は Instructor のトレースを自動的に取得します。トレースの記録を開始するには、weave.init(project_name="<YOUR-WANDB-PROJECT-NAME>") を呼び出し、その後は通常どおりライブラリを使用してください。

import instructor
import weave
from pydantic import BaseModel
from openai import OpenAI


# 希望する出力構造を定義する
class UserInfo(BaseModel):
    user_name: str
    age: int

# Weave を初期化する
weave.init(project_name="instructor-test")

# 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."}],
)

これで Weave は、Instructor を使用して行われるすべての LLM 呼び出しを追跡し、ログとして記録します。トレースは Weave の Web インターフェースで確認できます。

​

自分の op をトラッキングする

関数を @weave.op でラップすると、入力・出力やアプリのロジックのキャプチャが始まり、アプリ内でデータがどのように流れているかをデバッグできるようになります。op は深くネストしてツリー状の関数構造を作成でき、追跡したい関数を細かく指定できます。また、実験中のコードも自動でバージョニングされるため、まだ git にコミットしていないアドホックな変更内容も記録されます。

@weave.op でデコレートされた関数を作成するだけです。

以下の例では、extract_person という関数が、@weave.op でラップされたメトリクス関数になっています。これにより、OpenAI の chat completion 呼び出しなどの中間ステップがどのように処理されているかを確認できます。

import instructor
import weave
from openai import OpenAI
from pydantic import BaseModel


# 希望する出力構造を定義する
class Person(BaseModel):
    person_name: str
    age: int


# Weave を初期化する
weave.init(project_name="instructor-test")

# OpenAI クライアントにパッチを適用する
lm_client = instructor.from_openai(OpenAI())


# 自然言語から構造化データを抽出する
@weave.op()
def extract_person(text: str) -> Person:
    return lm_client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "user", "content": text},
        ],
        response_model=Person,
    )


person = extract_person("My name is John and I am 20 years old")

extract_person 関数に @weave.op デコレータを付与すると、関数の入力、出力、および関数内で行われるすべての内部 LM 呼び出しがトレースされます。さらに Weave は、Instructor によって生成された構造化オブジェクトも自動的に追跡し、バージョン管理します。

​

実験を効率化するために Model を作成する

多くの要素が絡み合うと、実験を整理するのは困難です。Model クラスを使うことで、システムプロンプトや使用しているモデルなど、アプリの実験に関する詳細を保存・整理できます。これにより、アプリのさまざまな反復バージョンを体系的に整理し、比較しやすくなります。

コードのバージョン管理や入出力の記録に加えて、Model はアプリケーションの挙動を制御する構造化されたパラメータも保持するため、どのパラメータ設定が最も有効だったかを簡単に見つけることができます。Weave Models は serve（後述）や Evaluation と組み合わせて使用することもできます。

以下の例では、PersonExtractor を使って実験できます。これらの設定のいずれかを変更するたびに、PersonExtractor の新しい バージョン が作成されます。

import asyncio
from typing import List, Iterable

import instructor
import weave
from openai import AsyncOpenAI
from pydantic import BaseModel


# 希望する出力構造を定義する
class Person(BaseModel):
    person_name: str
    age: int


# Weave を初期化する
weave.init(project_name="instructor-test")

# OpenAI クライアントにパッチを適用する
lm_client = instructor.from_openai(AsyncOpenAI())


class PersonExtractor(weave.Model):
    openai_model: str
    max_retries: int

    @weave.op()
    async def predict(self, text: str) -> List[Person]:
        model = await lm_client.chat.completions.create(
            model=self.openai_model,
            response_model=Iterable[Person],
            max_retries=self.max_retries,
            stream=True,
            messages=[
                {
                    "role": "system",
                    "content": "You are a perfect entity extraction system",
                },
                {
                    "role": "user",
                    "content": f"Extract `{text}`",
                },
            ],
        )
        return [m async for m in model]


model = PersonExtractor(openai_model="gpt-4", max_retries=2)
asyncio.run(model.predict("John is 30 years old"))

Model を使って呼び出しをトレースし、バージョン管理する

​

Weave モデルの提供

weave.Model オブジェクトへの Weave リファレンスがあれば、FastAPI サーバーを立ち上げて、それを serve できます。

任意の weave.Model の Weave リファレンスは、モデル画面に移動し、UI からコピーすることで取得できます。

次のコマンドをターミナルで実行して、モデルを提供できます。

weave serve weave://your_entity/project-name/YourModel:<hash>