참고소스 수정본

참고/instructor-main/docs/concepts/migration.md

@@ -0,0 +1,202 @@
+---
+title: Migration Guide
+description: Migrate from older Instructor patterns to the modern from_provider approach.
+---
+
+# Migration Guide
+
+This guide helps you migrate from older Instructor patterns to `from_provider`, the recommended approach for all providers.
+
+## Why Migrate?
+
+- **Simpler code**: Less boilerplate, easier to read
+- **Consistent interface**: Same pattern works for all providers
+- **Better type safety**: Improved IDE support
+- **Future-proof**: Recommended pattern going forward
+
+## Quick Reference
+
+| Old Pattern | New Pattern |
+|-------------|-------------|
+| `instructor.patch(openai.OpenAI())` | `instructor.from_provider("openai/model")` |
+| `instructor.apatch(openai.AsyncOpenAI())` | `instructor.from_provider("openai/model", async_client=True)` |
+| `from_openai(client)` | `instructor.from_provider("openai/model")` |
+| `from_anthropic(client)` | `instructor.from_provider("anthropic/model")` |
+| `from_genai(client)` | `instructor.from_provider("google/model")` |
+| `client.chat.completions.create(...)` | `client.create(...)` |
+| `client.messages.create(...)` | `client.create(...)` |
+
+## Basic Migration
+
+**Before:**
+
+```python
+import openai
+import instructor
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    name: str
+    age: int
+
+
+openai_client = openai.OpenAI()
+client = instructor.patch(openai_client)
+
+user = client.chat.completions.create(
+    model="gpt-4o-mini",
+    response_model=User,
+    messages=[{"role": "user", "content": "Extract: John is 30"}],
+)
+```
+
+**After:**
+
+```python
+import instructor
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    name: str
+    age: int
+
+
+client = instructor.from_provider("openai/gpt-4o-mini")
+
+user = client.create(
+    response_model=User,
+    messages=[{"role": "user", "content": "Extract: John is 30"}],
+)
+```
+
+## Async Migration
+
+**Before:**
+
+```python
+import openai
+import instructor
+
+openai_client = openai.AsyncOpenAI()
+client = instructor.apatch(openai_client)
+
+user = await client.chat.completions.create(...)
+```
+
+**After:**
+
+```python
+import instructor
+
+client = instructor.from_provider("openai/gpt-4o-mini", async_client=True)
+
+user = await client.create(...)
+```
+
+## Provider-Specific Migrations
+
+### Anthropic
+
+```python
+# Before (removed)
+import anthropic
+from instructor import from_anthropic
+
+client = from_anthropic(anthropic.Anthropic())
+user = client.messages.create(model="claude-3-5-sonnet", ...)
+
+# After
+client = instructor.from_provider("anthropic/claude-3-5-sonnet")
+user = client.create(...)
+```
+
+### Google/Gemini
+
+```python
+# Before (removed)
+import google.genai as genai
+from instructor import from_genai
+
+client = from_genai(genai.Client(), model="gemini-pro")
+user = client.generate_content(...)
+
+# After
+client = instructor.from_provider("google/gemini-pro")
+user = client.create(messages=[...])
+```
+
+## Configuration Options
+
+Pass configuration directly to `from_provider`:
+
+```python
+import instructor
+
+# Mode configuration
+client = instructor.from_provider("openai/gpt-4o-mini", mode=instructor.Mode.JSON)
+
+# Custom API settings
+client = instructor.from_provider(
+    "openai/gpt-4o-mini",
+    api_key="custom-key",
+    organization="org-id",
+    timeout=30.0,
+)
+```
+
+## Multiple Providers
+
+**Before:**
+
+```python
+import openai
+import anthropic
+import instructor
+from instructor import from_anthropic
+
+openai_client = instructor.patch(openai.OpenAI())
+anthropic_client = from_anthropic(anthropic.Anthropic())
+```
+
+**After:**
+
+```python
+import instructor
+
+openai_client = instructor.from_provider("openai/gpt-4o-mini")
+anthropic_client = instructor.from_provider("anthropic/claude-3-5-sonnet")
+```
+
+## Migration Checklist
+
+1. **Identify your current pattern**: `patch()`, `apatch()`, or `from_*()` functions
+2. **Find your model name**: e.g., `gpt-4o-mini`, `claude-3-5-sonnet`
+3. **Replace client creation**: Use `from_provider("provider/model")`
+4. **Update method calls**: Change to `client.create(...)`
+5. **Use standard message format**: `[{"role": "user", "content": "..."}]`
+6. **Test your code**
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `'Instructor' object has no attribute 'chat'` | Using old method call | Use `client.create()` instead of `client.chat.completions.create()` |
+| Invalid model string | Wrong format | Use `"provider/model-name"` format |
+| Message format error | Provider-specific format | Use standard `messages` list format |
+
+## Backward Compatibility
+
+Legacy helpers have been removed:
+
+- `instructor.patch()` → Use `from_provider` instead
+- `instructor.apatch()` → Use `from_provider` with `async_client=True`
+- `from_openai()`, `from_anthropic()`, etc. → Use `from_provider`
+
+Update all call sites before upgrading.
+
+## See Also
+
+- [from_provider Guide](./from_provider.md) - Complete guide to using from_provider
+- [Patching](./patching.md) - How Instructor enhances clients