참고소스 수정본
This commit is contained in:
LASTA_DEV01\lasta
469
참고/instructor-main/docs/integrations/openai-responses.md
Normal file
469
참고/instructor-main/docs/integrations/openai-responses.md
Normal file
@@ -0,0 +1,469 @@
|
||||
---
|
||||
title: "OpenAI Responses API Guide"
|
||||
description: "Learn how to use Instructor's new Responses API with OpenAI models for structured outputs. Complete guide with examples and best practices."
|
||||
---
|
||||
|
||||
# OpenAI Responses API Guide
|
||||
|
||||
The Responses API provides a more streamlined way to work with OpenAI models through Instructor. This guide covers everything you need to know about using the new Responses API for type-safe, validated outputs.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
import instructor
|
||||
from pydantic import BaseModel
|
||||
|
||||
# Initialize the client
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini", mode=instructor.Mode.RESPONSES_TOOLS
|
||||
)
|
||||
|
||||
|
||||
# Define your response model
|
||||
class User(BaseModel):
|
||||
name: str
|
||||
age: int
|
||||
|
||||
|
||||
# Create structured output
|
||||
profile = client.responses.create(
|
||||
input="Extract out Ivan is 28 years old",
|
||||
response_model=User,
|
||||
)
|
||||
|
||||
print(profile)
|
||||
#> name='Ivan' age=28
|
||||
```
|
||||
|
||||
## Response Modes
|
||||
|
||||
The Responses API supports two main modes:
|
||||
|
||||
1. `instructor.Mode.RESPONSES_TOOLS`: Standard mode for structured outputs
|
||||
2. `instructor.Mode.RESPONSES_TOOLS_WITH_INBUILT_TOOLS`: Enhanced mode that includes built-in tools like web search and file search
|
||||
|
||||
```python
|
||||
# Initialize the client
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini", mode=instructor.Mode.RESPONSES_TOOLS
|
||||
)
|
||||
```
|
||||
|
||||
## Core Methods
|
||||
|
||||
The Responses API provides several methods for creating structured outputs. Here's how to use each one:
|
||||
|
||||
### Basic Creation
|
||||
|
||||
The `create` method is the simplest way to get a structured output:
|
||||
|
||||
=== "Sync"
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
import instructor
|
||||
|
||||
class User(BaseModel):
|
||||
name: str
|
||||
age: int
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS
|
||||
)
|
||||
|
||||
profile = client.responses.create(
|
||||
input="Extract: Jason is 25 years old",
|
||||
response_model=User,
|
||||
)
|
||||
print(profile) # User(name='Jason', age=25)
|
||||
```
|
||||
|
||||
=== "Async"
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
import instructor
|
||||
import asyncio
|
||||
|
||||
class User(BaseModel):
|
||||
name: str
|
||||
age: int
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS,
|
||||
async_client=True
|
||||
)
|
||||
|
||||
async def main():
|
||||
profile = await client.responses.create(
|
||||
input="Extract: Jason is 25 years old",
|
||||
response_model=User,
|
||||
)
|
||||
print(profile) # User(name='Jason', age=25)
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
### Create with Completion
|
||||
|
||||
If you need the original completion object from OpenAI, you can do so with the `create_with_completion` method. This is useful when you have specific methods and data that you need to work from.
|
||||
|
||||
=== "Sync"
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
import instructor
|
||||
|
||||
class User(BaseModel):
|
||||
name: str
|
||||
age: int
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS
|
||||
)
|
||||
|
||||
response, completion = client.responses.create_with_completion(
|
||||
input="Extract: Jason is 25 years old",
|
||||
response_model=User,
|
||||
)
|
||||
print(response) # User(name='Jason', age=25)
|
||||
print(completion) # Raw completion object
|
||||
```
|
||||
|
||||
=== "Async"
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
import instructor
|
||||
import asyncio
|
||||
|
||||
class User(BaseModel):
|
||||
name: str
|
||||
age: int
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS,
|
||||
async_client=True
|
||||
)
|
||||
|
||||
async def main():
|
||||
response, completion = await client.responses.create_with_completion(
|
||||
input="Extract: Jason is 25 years old",
|
||||
response_model=User,
|
||||
)
|
||||
print(response) # User(name='Jason', age=25)
|
||||
print(completion) # Raw completion object
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
### Iterable Creation
|
||||
|
||||
If you're interested in extracting multiple instances of the same object, we provide a convinient wrapper to be able to do so.
|
||||
|
||||
=== "Sync"
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
from typing import Iterable
|
||||
import instructor
|
||||
|
||||
class User(BaseModel):
|
||||
name: str
|
||||
age: int
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS
|
||||
)
|
||||
|
||||
profiles = client.responses.create(
|
||||
input="Generate three fake profiles",
|
||||
response_model=Iterable[User],
|
||||
)
|
||||
|
||||
for profile in profiles:
|
||||
print(profile)
|
||||
|
||||
```
|
||||
|
||||
=== "Async"
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
from typing import Iterable
|
||||
import instructor
|
||||
import asyncio
|
||||
|
||||
class User(BaseModel):
|
||||
name: str
|
||||
age: int
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS,
|
||||
async_client=True
|
||||
)
|
||||
|
||||
async def main():
|
||||
profiles = await client.responses.create_iterable(
|
||||
input="Generate three fake profiles",
|
||||
response_model=User,
|
||||
)
|
||||
|
||||
async for profile in profiles:
|
||||
print(profile)
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
### Partial Creation
|
||||
|
||||
We also provide validated outputs that you can stream in real time. This is incredibly useful for working with dynamic generative UI.
|
||||
|
||||
=== "Sync"
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
import instructor
|
||||
|
||||
class User(BaseModel):
|
||||
name: str
|
||||
age: int
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS
|
||||
)
|
||||
|
||||
resp = client.responses.create_partial(
|
||||
input="Generate a fake profile",
|
||||
response_model=User,
|
||||
)
|
||||
|
||||
for user in resp:
|
||||
print(user) # Will show partial updates as they come in
|
||||
```
|
||||
|
||||
=== "Async"
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
import instructor
|
||||
import asyncio
|
||||
|
||||
class User(BaseModel):
|
||||
name: str
|
||||
age: int
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS,
|
||||
async_client=True
|
||||
)
|
||||
|
||||
async def main():
|
||||
resp = client.responses.create_partial(
|
||||
input="Generate a fake profile",
|
||||
response_model=User,
|
||||
)
|
||||
|
||||
async for user in resp:
|
||||
print(user) # Will show partial updates as they come in
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## Built-In Tools
|
||||
|
||||
The Responses API comes with powerful built-in tools that enhance the model's capabilities. These tools are managed by OpenAI, so you don't need to implement any additional code to use them.
|
||||
|
||||
For the most up-to-date documentation on how to use these tools, please refer to the [OpenAI Documentation](https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses)
|
||||
|
||||
### Web Search
|
||||
|
||||
The web search tool allows models to search the internet for real-time information. This is particularly useful for getting up-to-date information or verifying facts.
|
||||
|
||||
Model responses that use the web search tool will include two parts:
|
||||
|
||||
- A web_search_call output item with the ID of the search call.
|
||||
- A message output item containing:
|
||||
1. The text result in message.content[0].text
|
||||
2. Annotations message.content[0].annotations for the cited URLs
|
||||
|
||||
By default, the model's response will include inline citations for URLs found in the web search results.
|
||||
|
||||
In addition to this, the url_citation annotation object will contain the URL, title and location of the cited source. You can extract this information using the `create_with_completion` method.
|
||||
|
||||
=== "Sync"
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
import instructor
|
||||
|
||||
|
||||
class Citation(BaseModel):
|
||||
id: int
|
||||
url: str
|
||||
|
||||
|
||||
class Summary(BaseModel):
|
||||
citations: list[Citation]
|
||||
summary: str
|
||||
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS_WITH_INBUILT_TOOLS,
|
||||
async_client=False,
|
||||
)
|
||||
|
||||
response, completion = client.responses.create_with_completion(
|
||||
input="What are some of the best places to visit in New York for Latin American food?",
|
||||
tools=[{"type": "web_search_preview"}],
|
||||
response_model=Summary,
|
||||
)
|
||||
|
||||
print(response)
|
||||
# > citations=[Citation(id=1,url=....)]
|
||||
# > summary = New York City offers a rich variety of ...
|
||||
```
|
||||
|
||||
=== "Async"
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
import instructor
|
||||
import asyncio
|
||||
|
||||
|
||||
class Citation(BaseModel):
|
||||
id: int
|
||||
url: str
|
||||
|
||||
|
||||
class Summary(BaseModel):
|
||||
citations: list[Citation]
|
||||
summary: str
|
||||
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS_WITH_INBUILT_TOOLS,
|
||||
async_client=True,
|
||||
)
|
||||
|
||||
|
||||
async def main():
|
||||
response = await client.responses.create(
|
||||
input="What are some of the best places to visit in New York for Latin American food?",
|
||||
tools=[{"type": "web_search_preview"}],
|
||||
response_model=Summary,
|
||||
)
|
||||
print(response)
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
# > citations=[Citation(id=1,url=....)]
|
||||
# > summary = New York City offers a rich variety of ...
|
||||
```
|
||||
|
||||
You can customize the web search behavior with additional parameters:
|
||||
|
||||
```python
|
||||
response = client.responses.create(
|
||||
input="What are the best restaurants around Granary Square?",
|
||||
tools=[{
|
||||
"type": "web_search_preview",
|
||||
"user_location": {
|
||||
"type": "approximate",
|
||||
"country": "GB",
|
||||
"city": "London",
|
||||
"region": "London",
|
||||
}
|
||||
}],
|
||||
response_model=Summary,
|
||||
)
|
||||
```
|
||||
|
||||
### File Search
|
||||
|
||||
The file search tool enables models to retrieve information from your knowledge base through semantic and keyword search. This is useful for augmenting the model's knowledge with your own documents.
|
||||
|
||||
This makes it easy to build RAG applications out of the box
|
||||
|
||||
=== "Sync"
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
import instructor
|
||||
|
||||
class Citation(BaseModel):
|
||||
file_id: int
|
||||
file_name: str
|
||||
excerpt: str
|
||||
|
||||
class Response(BaseModel):
|
||||
citations: list[Citation]
|
||||
response: str
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS_WITH_INBUILT_TOOLS
|
||||
)
|
||||
|
||||
response = client.responses.create(
|
||||
input="How much does the Kyoto itinerary cost?",
|
||||
tools=[{
|
||||
"type": "file_search",
|
||||
"vector_store_ids": ["your_vector_store_id"],
|
||||
"max_num_results": 2,
|
||||
}],
|
||||
response_model=Response,
|
||||
)
|
||||
```
|
||||
|
||||
=== "Async"
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
import instructor
|
||||
import asyncio
|
||||
|
||||
class Citation(BaseModel):
|
||||
file_id: int
|
||||
file_name: str
|
||||
excerpt: str
|
||||
|
||||
class Response(BaseModel):
|
||||
citations: list[Citation]
|
||||
response: str
|
||||
|
||||
client = instructor.from_provider(
|
||||
"openai/gpt-4.1-mini",
|
||||
mode=instructor.Mode.RESPONSES_TOOLS_WITH_INBUILT_TOOLS,
|
||||
async_client=True
|
||||
)
|
||||
|
||||
async def main():
|
||||
response = await client.responses.create(
|
||||
input="How much does the Kyoto itinerary cost?",
|
||||
tools=[{
|
||||
"type": "file_search",
|
||||
"vector_store_ids": ["your_vector_store_id"],
|
||||
"max_num_results": 2,
|
||||
}],
|
||||
response_model=Response,
|
||||
)
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## Related Resources
|
||||
|
||||
- [OpenAI Documentation](https://platform.openai.com/docs)
|
||||
- [Instructor Core Concepts](../concepts/index.md)
|
||||
- [Type Validation Guide](../concepts/validation.md)
|
||||
- [Advanced Usage Examples](../examples/index.md)
|
||||
Reference in New Issue
Block a user