URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK: Ghi chú cài đặt Flatkey

Việc thiết lập URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK không chỉ đơn thuần là thay thế một chuỗi. Phần hữu ích là trỏ nhà cung cấp AI SDK đến Flatkey, nhưng công việc an toàn cho môi trường production là xác minh các bí danh mô hình, họ điểm cuối, hành vi streaming, lệnh gọi công cụ, bằng chứng sử dụng, kiểm soát hạn ngạch và khả năng rollback trước khi chuyển lưu lượng người dùng.

Hướng dẫn này dành cho các nhà phát triển, đội ngũ sản phẩm AI, kỹ sư nền tảng, người xây dựng tự động hóa, nhà điều hành tài chính và người đánh giá mua sắm sử dụng AI SDK trong một route Next.js, server action, worker, queue, hoặc agent loop. Nó được cập nhật vào ngày 29 tháng 6 năm 2026 từ tài liệu AI SDK hiện tại, kiểm tra kiểu dữ liệu với các gói AI SDK hiện tại và các trang công khai của Flatkey. Các đoạn mã là mẫu. Không có khóa API Flatkey thực tế nào được cung cấp trong tác vụ này, vì vậy hãy chạy các bài kiểm tra sơ bộ (smoke tests) bằng khóa của riêng bạn, URL cơ sở từ bảng điều khiển Flatkey hiện tại và các bí danh mô hình đã được kích hoạt cho tài khoản của bạn.

Trả lời nhanh: URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK

Để thiết lập URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK với Flatkey, hãy bắt đầu với gói nhà cung cấp tương thích OpenAI chính thức. Tạo một nhà cung cấp với createOpenAICompatible, đặt baseURL thành URL cơ sở Flatkey hiện tại từ bảng điều khiển của bạn, đặt apiKey thành khóa Flatkey của bạn và sử dụng các bí danh mô hình Flatkey trong generateText hoặc streamText.

npm install ai @ai-sdk/openai-compatible zod

export FLATKEY_API_KEY="fk_your_key"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1" # Copy the current value from Flatkey
export FLATKEY_MODEL="your-flatkey-model-alias"

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Reply with one short Flatkey AI SDK routing check.',
});

console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);
console.log(result.warnings);

Đó là cấu hình tối thiểu để di chuyển URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK. Đừng dừng lại ở đó. Một phản hồi văn bản thành công chỉ chứng minh rằng một dạng yêu cầu đã đến được một bí danh mô hình. Nó không chứng minh được việc sử dụng streaming, công cụ, đầu ra có cấu trúc, khả năng hiển thị chi phí, hành vi hạn ngạch hoặc khả năng rollback.

Tài liệu AI SDK hiện tại hỗ trợ những gì

Tài liệu AI SDK hiện tại có hai hướng tiếp cận liên quan. Gói nhà cung cấp Tương thích OpenAI được xây dựng cho các nhà cung cấp triển khai API của OpenAI. Nó cung cấp createOpenAICompatible với các tùy chọn bao gồm name, apiKey, baseURL, headers, queryParams, fetch tùy chỉnh, includeUsage, supportsStructuredOutputs, biến đổi nội dung yêu cầu và trích xuất siêu dữ liệu.

Gói nhà cung cấp OpenAI cũng hỗ trợ createOpenAI({ baseURL }) cho các thiết lập tùy chỉnh, bao gồm cả máy chủ proxy. Nhà cung cấp Tương thích OpenAI là lựa chọn mặc định rõ ràng hơn cho URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK vì tên nhà cung cấp, trích xuất siêu dữ liệu tùy chỉnh, các tùy chọn dành riêng cho nhà cung cấp và tên nhà máy mô hình của nó được thiết kế cho các route tương thích OpenAI nhưng không phải của OpenAI.

Bằng chứng mới nhất từ Flatkey cần sử dụng cẩn thận

Trang chủ của Flatkey được kiểm tra vào ngày 29 tháng 6 năm 2026 có tiêu đề One API gateway for production AI teams và mô tả meta cho biết Flatkey hợp nhất quyền truy cập mô hình, định tuyến, thanh toán, phân tích sử dụng và kiểm soát vận hành. API giá trực tiếp trả về 633 hàng mô hình, 23 nhà cung cấp và các họ điểm cuối cho /v1/chat/completions, /v1/responses, /v1/messages, /v1beta/models/{model}:generateContent, /v1/images/generations, và /v1/video/generations.

Hãy sử dụng những thông tin đó như bằng chứng công khai có ghi ngày tháng về định vị và cấu trúc danh mục, chứ không phải là bằng chứng cho thấy mọi tài khoản đều có thể gọi mọi route, mọi bí danh mô hình đều có sẵn, hoặc mọi tính năng đều được kích hoạt. Trước khi đưa vào môi trường production, các kiểm tra URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK của bạn nên sử dụng chính xác khóa, URL cơ sở, bí danh mô hình, họ điểm cuối và đường dẫn tính năng mà ứng dụng của bạn sẽ gửi.

URL cơ sở và thiết lập môi trường

Giữ URL cơ sở, khóa và bí danh mô hình trong các biến môi trường. Điều này giúp việc triển khai URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK có thể được xem xét trong cấu hình triển khai thay vì bị chôn vùi bên trong các trình xử lý tuyến đường, tệp nhắc lệnh và worker.

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

Sau đó, hãy giữ việc định tuyến khối lượng công việc tách biệt với thiết lập vận chuyển. URL cơ sở cho SDK biết nơi gửi yêu cầu. Bí danh mô hình quyết định tuyến đường Flatkey và mô hình ngược dòng mà bạn đang yêu cầu.

const MODEL_ROUTES = {
  supportTriage: 'FLATKEY_SUPPORT_MODEL',
  workflowPlanning: 'FLATKEY_PLANNING_MODEL',
  codeReview: 'FLATKEY_CODE_MODEL',
  fallback: 'FLATKEY_FALLBACK_MODEL',
} as const;

function modelFor(routeName: keyof typeof MODEL_ROUTES) {
  return flatkey.chatModel(requiredEnv(MODEL_ROUTES[routeName]));
}

Mẫu này ngăn các nhóm phân tán tên nhà cung cấp, bí danh mô hình và URL cơ sở trên toàn bộ codebase. Nó cũng cung cấp cho các nhóm tài chính và vận hành một bộ tên khối lượng công việc ổn định để đối chiếu với các hàng dữ liệu sử dụng.

Kiểm tra sơ bộ văn bản không truyền trực tuyến trước

Bắt đầu với generateText. Nó cung cấp cho bạn một đối tượng kết quả đơn giản với văn bản, lý do kết thúc, mức sử dụng, cảnh báo, các bước và siêu dữ liệu phản hồi. Sử dụng nó để chứng minh xác thực, hình dạng URL cơ sở, bí danh mô hình và khả năng hiển thị mức sử dụng trước khi kiểm tra truyền trực tuyến hoặc các công cụ.

import { generateText } from 'ai';

const result = await generateText({
  model: modelFor('supportTriage'),
  prompt: 'Reply with one short migration readiness check.',
});

console.log({
  text: result.text,
  finishReason: result.finishReason,
  usage: result.usage,
  warnings: result.warnings,
});

Chỉ phê duyệt lần kiểm tra URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK đầu tiên này nếu các trường văn bản được tạo, bí danh mô hình, lý do kết thúc và mức sử dụng đủ tốt cho nhu cầu ghi nhật ký và xem xét của ứng dụng của bạn. Nếu lệnh gọi trả về văn bản nhưng không thể tìm thấy mức sử dụng trong hồ sơ Flatkey, việc di chuyển chưa sẵn sàng cho môi trường sản xuất.

Kiểm tra truyền trực tuyến riêng biệt

Truyền trực tuyến có một bề mặt lỗi khác. Nó liên quan đến việc truyền trực tuyến phản hồi, thời gian chờ của serverless, hủy bỏ từ giao diện người dùng, xử lý lỗi và hạch toán mức sử dụng. Tài liệu AI SDK hiển thị streamText, result.textStream, một callback onError, và các promise kết quả như result.usage. Nhà cung cấp Tương thích OpenAI cũng có includeUsage cho siêu dữ liệu phản hồi truyền trực tuyến khi nhà cung cấp hỗ trợ nó.

import { streamText } from 'ai';

const stream = streamText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Stream three short setup checks.',
  onError({ error }) {
    console.error(error);
  },
});

for await (const textPart of stream.textStream) {
  process.stdout.write(textPart);
}

const usage = await stream.usage;
console.log({ usage });

Chỉ bật tính năng truyền trực tuyến sau khi bí danh mô hình Flatkey được chọn đã chứng tỏ sự ổn định dưới hình dạng yêu cầu thực tế của bạn. Nếu văn bản truyền trực tuyến hoạt động nhưng mức sử dụng không đầy đủ, hãy quyết định xem nhóm của bạn có thể thu thập dữ liệu sử dụng từ hồ sơ Flatkey thay vì từ phản hồi luồng trước khi lưu lượng người dùng chuyển sang hay không.

Xác minh các lệnh gọi công cụ với cùng một bí danh

API công cụ của AI SDK sử dụng một đối tượng tools, trình trợ giúp tool, một inputSchema, và một hàm execute tùy chọn. Một lượt trò chuyện thông thường không phê duyệt việc gọi công cụ. Hãy kiểm tra một schema nhỏ trước, sau đó mở rộng ra bộ công cụ mà các agent của bạn thực sự sử dụng.

import { generateText, isStepCount, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_TOOL_MODEL')),
  tools: {
    routeReadiness: tool({
      description: 'Return the readiness state for a Flatkey route.',
      inputSchema: z.object({
        routeName: z.string().describe('Internal route name to inspect'),
      }),
      execute: async ({ routeName }) => ({
        routeName,
        checked: true,
      }),
    }),
  },
  stopWhen: isStepCount(2),
  prompt: 'Use the tool for route supportTriage.',
});

console.log(result.toolCalls);
console.log(result.toolResults);
console.log(result.usage);

Đối với lưu lượng agent, hãy ghi lại xem mô hình có gọi đúng công cụ mong đợi không, liệu đầu vào có được xác thực không, liệu kết quả công cụ có trả về một cách sạch sẽ không, và liệu hàng dữ liệu sử dụng Flatkey có thể được liên kết trở lại với cùng một tuyến đường không. Nếu các schema nghiêm ngặt, luồng phê duyệt, hoặc các lệnh gọi công cụ song song là quan trọng, hãy kiểm tra các tính năng đó với bí danh mô hình chính xác.

Khi nào nên sử dụng createOpenAI thay thế

Nếu ứng dụng của bạn đã sử dụng @ai-sdk/openai ở mọi nơi, tùy chọn baseURL của nhà cung cấp OpenAI có thể là một con đường di chuyển ít thay đổi hơn. Đây vẫn là một thiết lập URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK, nhưng bạn nên rõ ràng hơn về việc lựa chọn API mô hình.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const flatkeyViaOpenAIProvider = createOpenAI({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
});

const result = await generateText({
  model: flatkeyViaOpenAIProvider.chat(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Reply with one short OpenAI-provider base URL check.',
});

Tài liệu hiện tại của nhà cung cấp OpenAI cho biết Responses là API mặc định cho nhà cung cấp OpenAI kể từ AI SDK 5 trừ khi bạn chỉ định một tuyến đường như .chat(...). Đó là lý do tại sao ví dụ trên sử dụng .chat(...) một cách rõ ràng. Nếu bạn định kiểm tra họ điểm cuối /v1/responses của Flatkey, hãy coi đó là một lần kiểm tra tuyến đường riêng biệt với một bí danh mô hình và đường dẫn khôi phục riêng.

Danh sách kiểm tra cài đặt

Các chế độ lỗi thường gặp

Vị trí của hướng dẫn này trong các hướng dẫn khác của Flatkey

Nếu bạn cần một lộ trình di chuyển rộng hơn, hãy bắt đầu với hướng dẫn di chuyển API tương thích OpenAI. Đối với các mẫu thiết lập công cụ liền kề, hãy xem lại hướng dẫn thiết lập API Cherry Studio và hướng dẫn cc-switch Claude Code Flatkey. Sử dụng bảng giá Flatkey để kiểm tra danh mục mô hình hiện tại, sau đó lấy khóa khi bạn sẵn sàng chạy các bài kiểm tra khói trong tài khoản của riêng mình.

Câu hỏi thường gặp

Làm cách nào để đặt URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK cho Flatkey?

Tạo một nhà cung cấp tương thích OpenAI với createOpenAICompatible, đặt baseURL thành URL cơ sở Flatkey hiện tại, đặt apiKey thành khóa Flatkey của bạn và chuyển một bí danh mô hình Flatkey đến generateText hoặc streamText.

Tôi nên sử dụng @ai-sdk/openai-compatible hay @ai-sdk/openai?

Sử dụng @ai-sdk/openai-compatible cho một thiết lập Flatkey mới vì nó được thiết kế cho các nhà cung cấp tương thích OpenAI. Sử dụng @ai-sdk/openai với createOpenAI({ baseURL }) khi ứng dụng của bạn đã chuẩn hóa trên nhà cung cấp OpenAI và bạn muốn có sự khác biệt về mã nhỏ hơn.

URL cơ sở có cần bao gồm /v1 không?

Sử dụng giá trị được hiển thị trong bảng điều khiển Flatkey hiện tại của bạn. Trong hầu hết các mẫu SDK tương thích OpenAI, URL cơ sở bao gồm tiền tố phiên bản để các lệnh gọi SDK có thể nối thêm các đường dẫn như /chat/completions một cách chính xác.

Một URL cơ sở Flatkey có thể định tuyến nhiều mô hình không?

Định vị công khai của Flatkey là một cổng duy nhất để truy cập mô hình, định tuyến, thanh toán, phân tích sử dụng và kiểm soát hoạt động. Trong ứng dụng của bạn, vẫn ánh xạ mỗi khối lượng công việc tới một bí danh mô hình Flatkey rõ ràng và kiểm tra bí danh thực tế trước khi lưu lượng truy cập di chuyển.

Các đoạn mã AI SDK này đã được kiểm tra chưa?

Các đoạn mã đã được kiểm tra kiểu vào ngày 29 tháng 6 năm 2026 với ai@7.0.4, @ai-sdk/openai-compatible@3.0.1, @ai-sdk/openai@4.0.2, TypeScript và Zod. Chúng không được thực thi trên Flatkey vì không có khóa API Flatkey trực tiếp nào có sẵn trong môi trường chạy này.

Kết luận

Việc di chuyển **URL cơ sở của nhà cung cấp tùy chỉnh Vercel AI SDK** nên là một thay đổi nhỏ về nhà cung cấp đi kèm với một danh sách kiểm tra xác minh nghiêm ngặt. Sử dụng createOpenAICompatible cho nhà cung cấp Flatkey, giữ URL cơ sở và bí danh mô hình trong cấu hình, kiểm tra văn bản không phát trực tuyến trước, kiểm tra riêng việc phát trực tuyến và các lệnh gọi công cụ, xác nhận bằng chứng sử dụng trong Flatkey, và giữ sẵn sàng phương án khôi phục cho đến khi lưu lượng truy cập sản phẩm ổn định. Khi các bước kiểm tra đã sẵn sàng, hãy lấy một khóa và chạy các bài kiểm tra sơ bộ với các bí danh mô hình của riêng bạn.