zhongwei/gh-jezweb-claude-skills-skills-openai-assistants

Files

Zhongwei Li 0c577730d5 Initial commit

2025-11-30 08:25:15 +08:00

3.6 KiB

Raw Blame History

Migration from Assistants API v1 to v2

v1 Deprecated: December 18, 2024 (no longer accessible) v2 Status: Production (Deprecated H1 2026 in favor of Responses API)

Breaking Changes

1. Retrieval Tool → File Search

v1:

{
  tools: [{ type: "retrieval" }],
  file_ids: ["file_abc123", "file_def456"]
}

v2:

{
  tools: [{ type: "file_search" }],
  tool_resources: {
    file_search: {
      vector_store_ids: ["vs_abc123"]
    }
  }
}

Action: Create vector stores and migrate files.

2. File Attachments

v1: Files attached at assistant level v2: Files attached at message level

v1:

const assistant = await openai.beta.assistants.create({
  file_ids: ["file_abc123"],
});

v2:

await openai.beta.threads.messages.create(thread.id, {
  content: "...",
  attachments: [{
    file_id: "file_abc123",
    tools: [{ type: "code_interpreter" }]
  }],
});

3. Instructions Character Limit

v1: 32,000 characters
v2: 256,000 characters (8x increase)

Migration Steps

Step 1: Create Vector Stores

// Old v1 approach
const assistant = await openai.beta.assistants.create({
  tools: [{ type: "retrieval" }],
  file_ids: fileIds, // Direct attachment
});

// New v2 approach
const vectorStore = await openai.beta.vectorStores.create({
  name: "Knowledge Base",
});

await openai.beta.vectorStores.fileBatches.create(vectorStore.id, {
  file_ids: fileIds,
});

const assistant = await openai.beta.assistants.create({
  tools: [{ type: "file_search" }],
  tool_resources: {
    file_search: {
      vector_store_ids: [vectorStore.id],
    },
  },
});

Step 2: Update File Attachments

// Move file attachments from assistant to messages
await openai.beta.threads.messages.create(thread.id, {
  role: "user",
  content: "Analyze this file",
  attachments: [{
    file_id: "file_abc123",
    tools: [{ type: "code_interpreter" }],
  }],
});

Step 3: Test Thoroughly

Verify file search returns expected results
Check Code Interpreter file handling
Test streaming if used
Validate function calling patterns

New v2 Features

1. Massive File Capacity

v1: ~20 files per assistant
v2: 10,000 files per assistant (500x increase)

2. Better Search Performance

Vector + keyword search
Parallel query processing
Advanced reranking

3. Auto-Expiration

const vectorStore = await openai.beta.vectorStores.create({
  expires_after: {
    anchor: "last_active_at",
    days: 30,
  },
});

4. Batch File Operations

const batch = await openai.beta.vectorStores.fileBatches.create(vectorStoreId, {
  file_ids: ["file_1", "file_2", "file_3"],
});

Cost Implications

v1 (Deprecated)

No separate storage costs for retrieval

v2

Storage: $0.10/GB/day for vector stores
Free tier: First 1GB
Optimization: Use auto-expiration

Recommended Path Forward

For existing v1 applications:

Migrate to v2 immediately (v1 no longer works)
Plan migration to Responses API (v2 sunset in H1 2026)

For new applications:

✅ Use Responses API
❌ Don't use Assistants API (being deprecated)

Migration Checklist

Update to openai SDK 6.7.0+
Create vector stores for file search
Migrate file attachments to message level
Test file search results
Update to file_search from retrieval
Implement vector store cleanup
Monitor storage costs
Plan migration to Responses API

Last Updated: 2025-10-25

3.6 KiB Raw Blame History