plugin-ai-api 1.1.0 → 1.1.2

package/src/server/migrations/20260903000000-seed-sample-response-records.ts

@@ -0,0 +1,162 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { Migration } from '@nocobase/server';
+
+const SAMPLE_IDS = ['resp_sample_welcome', 'resp_sample_followup'];
+
+export default class SeedSampleResponseRecord extends Migration {
+  on = 'afterSync' as const;
+
+  async up() {
+    const collection = this.db.getCollection('aiApiResponseRecords');
+    if (!collection || !(await collection.existsInDb())) return;
+
+    // Never seed demo content in production unless the operator opts in explicitly.
+    if (process.env.NODE_ENV === 'production' && process.env.AI_API_SEED_SAMPLE_RESPONSES !== 'true') {
+      this.app.logger.info(
+        '[ai-api] Skipped sample response records in production (set AI_API_SEED_SAMPLE_RESPONSES=true to enable).',
+      );
+      return;
+    }
+
+    const rootUser = await this.db.getRepository('users').findOne({ filter: { 'roles.name': 'root' } });
+    if (!rootUser) {
+      this.app.logger.warn('[ai-api] Skipped sample response records because no root user exists.');
+      return;
+    }
+    const repository = this.db.getRepository('aiApiResponseRecords');
+
+    const now = Math.floor(Date.now() / 1000);
+    const expiresAt = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+    const firstOutput = {
+      id: SAMPLE_IDS[0],
+      object: 'response',
+      created_at: now,
+      completed_at: now,
+      status: 'completed',
+      error: null,
+      incomplete_details: null,
+      instructions: null,
+      max_output_tokens: null,
+      model: 'sample/gpt-4',
+      output: [
+        {
+          id: 'msg_sample_welcome',
+          type: 'message',
+          status: 'completed',
+          role: 'assistant',
+          content: [
+            {
+              type: 'output_text',
+              text: 'Hello! Welcome to the NocoBase AI API. How can I help you today?',
+              annotations: [],
+            },
+          ],
+        },
+      ],
+      output_text: 'Hello! Welcome to the NocoBase AI API. How can I help you today?',
+      parallel_tool_calls: true,
+      previous_response_id: null,
+      reasoning: null,
+      service_tier: 'default',
+      temperature: null,
+      text: null,
+      tool_choice: 'auto',
+      tools: [],
+      top_p: null,
+      truncation: 'disabled',
+      usage: {
+        input_tokens: 15,
+        input_tokens_details: { cached_tokens: 0 },
+        output_tokens: 20,
+        output_tokens_details: { reasoning_tokens: 0 },
+        total_tokens: 35,
+      },
+      metadata: { sample: 'true', purpose: 'documentation' },
+    };
+
+    const firstValues = {
+      responseId: SAMPLE_IDS[0],
+      userId: rootUser.get('id'),
+      model: firstOutput.model,
+      input: 'Hello! I am testing the Responses API.',
+      output: firstOutput,
+      previousResponseId: null,
+      metadata: firstOutput.metadata,
+      expiresAt,
+    };
+
+    const secondOutput = {
+      ...firstOutput,
+      id: SAMPLE_IDS[1],
+      created_at: now + 60,
+      completed_at: now + 60,
+      output: [
+        {
+          id: 'msg_sample_followup',
+          type: 'message',
+          status: 'completed',
+          role: 'assistant',
+          content: [
+            {
+              type: 'output_text',
+              text: 'I can help with questions, code, data analysis, and more.',
+              annotations: [],
+            },
+          ],
+        },
+      ],
+      output_text: 'I can help with questions, code, data analysis, and more.',
+      previous_response_id: SAMPLE_IDS[0],
+      usage: {
+        input_tokens: 25,
+        input_tokens_details: { cached_tokens: 0 },
+        output_tokens: 15,
+        output_tokens_details: { reasoning_tokens: 0 },
+        total_tokens: 40,
+      },
+    };
+    const secondValues = {
+      responseId: SAMPLE_IDS[1],
+      userId: rootUser.get('id'),
+      model: secondOutput.model,
+      input: 'What can you help me with?',
+      output: secondOutput,
+      previousResponseId: SAMPLE_IDS[0],
+      metadata: secondOutput.metadata,
+      expiresAt,
+    };
+
+    // Create each missing sample independently inside one transaction, so a rerun after a
+    // partial failure still seeds the remaining record without duplicating the existing one.
+    const candidates = [firstValues, secondValues];
+    await this.db.sequelize.transaction(async (transaction) => {
+      for (const values of candidates) {
+        const exists = await repository.findOne({ filter: { responseId: values.responseId }, transaction });
+        if (!exists) {
+          await repository.create({ values, transaction });
+        }
+      }
+    });
+    this.app.logger.info('[ai-api] Seeded sample Responses API records for the root user.');
+  }
+
+  async down() {
+    const repository = this.db.getRepository('aiApiResponseRecords');
+    const records = await repository.find({ filter: { responseId: { $in: SAMPLE_IDS } } });
+    for (const record of records) {
+      const metadata = record.get('metadata');
+      // Only remove records we actually seeded — a user-owned record may reuse a sample id.
+      if (metadata && typeof metadata === 'object' && (metadata as Record<string, unknown>).sample === 'true') {
+        await repository.destroy({ filterByTk: record.get('id') });
+      }
+    }
+  }
+}

package/src/server/plugin.ts

@@ -12,11 +12,12 @@ import type { Transactionable } from '@nocobase/database';
 import { createAiLlmRouter, AI_LLM_PREFIX } from './routes/router';
 import aiApiConfigResource from './resource/ai-api-config';
 import aiApiUsageMonitorResource from './resource/ai-api-usage-monitor';
-import aiApiUsageGroupsResource from './resource/ai-api-usage-groups';
 import { RateLimiter } from './utils/rate-limiter';
 import { invalidateRolePermissionCache } from './middleware/role-permission';
+import { blockResponseRecordResource } from './middleware/response-record-resource';
 import { invalidateGroupAccessCache } from './utils/user-permissions';
-import { validateModelPrice, validateModelMetadata, validateQuotaPolicy } from './validation';
+import { cleanupExpiredResponseRecords } from './utils/response-store';
+import { validateModelPrice, validateModelMetadata, validateQuotaPolicy, validateVirtualModel } from './validation';
 import { AI_API_ACL_SNIPPET } from '../constants';
 import {
   FileProcessorService,
@@ -52,6 +53,7 @@ export class PluginAiApiServer extends Plugin {
   fileProcessorService = new FileProcessorService();
 
   private gcInterval: NodeJS.Timeout | null = null;
+  private responseCleanupInterval: NodeJS.Timeout | null = null;
 
   async afterAdd() {}
 
@@ -62,6 +64,9 @@ export class PluginAiApiServer extends Plugin {
     this.app.db.on('aiApiModelMetadata.beforeSave', (model) => {
       validateModelMetadata(model);
     });
+    this.app.db.on('aiApiVirtualModels.beforeSave', (model) => {
+      validateVirtualModel(model);
+    });
     this.app.db.on('aiApiUsageGroups.beforeSave', async (model, options) => {
       validateQuotaPolicy(model);
       // The partial unique index on isDefault is not supported on MySQL,
@@ -82,6 +87,19 @@ export class PluginAiApiServer extends Plugin {
     this.app.db.on('aiApiGroupMembers.beforeSave', async (model, options) => {
       const userId = model.get('userId');
       if (!userId) return;
+      // The default group is a fallback, not a membership target: an explicit row would pin the
+      // user there and make them invisible to any unassigned-users filter. Reject it here so the
+      // rule holds whether the row comes from a custom action or a plain aiApiGroupMembers:create.
+      const targetGroupId = model.get('groupId');
+      if (targetGroupId) {
+        const targetGroup = await this.db.getRepository('aiApiUsageGroups').findOne({
+          filterByTk: targetGroupId,
+          transaction: options?.transaction,
+        });
+        if (targetGroup?.get('isDefault')) {
+          throw new Error('Cannot add members to the default group: users without another group use it automatically.');
+        }
+      }
       const existing = await this.db.getRepository('aiApiGroupMembers').findOne({
         filter: { userId },
         transaction: options?.transaction,
@@ -95,24 +113,16 @@ export class PluginAiApiServer extends Plugin {
       if (model.get('isDefault')) {
         throw new Error('The default usage group cannot be deleted.');
       }
+      // Drop membership rows so the affected users fall back to the default group
+      // implicitly. Rows are destroyed one by one to keep the repository-level
+      // destroy events firing for any listener that tracks membership changes.
       const members = await this.db.getRepository('aiApiGroupMembers').find({
         filter: { groupId: model.get('id') },
         transaction: options?.transaction,
       });
-      if (members.length === 0) return;
-
-      const defaultGroup = await this.db.getRepository('aiApiUsageGroups').findOne({
-        filter: { isDefault: true },
-        transaction: options?.transaction,
-      });
-      if (!defaultGroup) {
-        throw new Error('Default usage group is missing; cannot reassign members.');
-      }
-
       for (const member of members) {
-        await this.db.getRepository('aiApiGroupMembers').update({
+        await this.db.getRepository('aiApiGroupMembers').destroy({
           filterByTk: member.get('id'),
-          values: { groupId: defaultGroup.get('id') },
           transaction: options?.transaction,
         });
       }
@@ -151,13 +161,20 @@ export class PluginAiApiServer extends Plugin {
     // 2. Register admin config resource
     this.app.resourceManager.define(aiApiConfigResource);
     this.app.resourceManager.define(aiApiUsageMonitorResource);
-    this.app.resourceManager.define(aiApiUsageGroupsResource);
 
-    this.app.db.on('aiApiRolePermissions.afterSave', (model) => {
-      invalidateRolePermissionCache(model.get('roleName'));
+    // Stored prompts are only exposed through the owner-scoped OpenAI routes. This
+    // explicit policy also blocks root, whose generic NocoBase ACL bypass is unconditional.
+    this.app.resourceManager.use(blockResponseRecordResource(), {
+      tag: 'aiApiResponseRecordsPrivate',
+      after: 'auth',
+      before: 'acl',
     });
-    this.app.db.on('aiApiRolePermissions.afterDestroy', (model) => {
-      invalidateRolePermissionCache(model.get('roleName'));
+
+    this.app.db.on('aiApiRolePermissions.afterSave', (model, options) => {
+      this.invalidateRolePermissionSync(model.get('roleName'), options?.transaction);
+    });
+    this.app.db.on('aiApiRolePermissions.afterDestroy', (model, options) => {
+      this.invalidateRolePermissionSync(model.get('roleName'), options?.transaction);
     });
 
     this.app.db.on('aiApiUsageGroups.afterSave', (model, options) => {
@@ -175,6 +192,7 @@ export class PluginAiApiServer extends Plugin {
         'aiApiRolePermissions:*',
         'aiApiModelPrices:*',
         'aiApiModelMetadata:*',
+        'aiApiVirtualModels:*',
         'aiApiUsageGroups:*',
         'aiApiGroupMembers:*',
         'aiApiGroupQuotaBuckets:list',
@@ -189,6 +207,24 @@ export class PluginAiApiServer extends Plugin {
     //    .unref() prevents this timer from keeping the process alive on shutdown.
     this.gcInterval = setInterval(() => this.rateLimiter.gc(), 5 * 60 * 1000);
     this.gcInterval.unref();
+
+    // Expired stored responses are removed daily; run once at startup as well.
+    this.cleanupResponseRecords();
+    this.responseCleanupInterval = setInterval(() => this.cleanupResponseRecords(), 24 * 60 * 60 * 1000);
+    this.responseCleanupInterval.unref();
+  }
+
+  /**
+   * Drop a role's cached permission record on every node.
+   *
+   * Mirrors invalidateGroupAccess: the local call is not redundant because
+   * syncMessageManager hardcodes skipSelf, so the publishing node never receives
+   * its own message. Passing the transaction defers the broadcast until the
+   * write commits, so other nodes cannot re-read the old row and re-cache it.
+   */
+  private invalidateRolePermissionSync(roleName: unknown, transaction?: Transactionable['transaction']) {
+    invalidateRolePermissionCache(roleName as string | undefined);
+    this.sendSyncMessage({ type: 'invalidateRolePermission', roleName }, { transaction });
   }
 
   /**
@@ -206,9 +242,11 @@ export class PluginAiApiServer extends Plugin {
   /**
    * Received only on the *other* nodes (skipSelf), so this must not re-broadcast.
    */
-  async handleSyncMessage(message: { type?: string; groupId?: unknown }) {
+  async handleSyncMessage(message: { type?: string; groupId?: unknown; roleName?: unknown }) {
     if (message?.type === 'invalidateGroupAccess') {
       invalidateGroupAccessCache(message.groupId as string | number | bigint);
+    } else if (message?.type === 'invalidateRolePermission') {
+      invalidateRolePermissionCache(message.roleName as string | undefined);
     }
   }
 
@@ -227,6 +265,19 @@ export class PluginAiApiServer extends Plugin {
       });
     }
 
+    // Root and admin get explicit AI API permission rows on fresh installs. There is no
+    // built-in role bypass anymore, so without these rows even root/admin would be denied
+    // until an admin grants access in Settings → Users & Permissions.
+    for (const roleName of ['root', 'admin']) {
+      const perm = await this.db.getRepository('aiApiRolePermissions').findOne({
+        filter: { roleName },
+      });
+      if (!perm) {
+        await this.db.getRepository('aiApiRolePermissions').create({
+          values: { roleName, enabled: true, allowAllEmployees: true, allowedEmployees: [] },
+        });
+      }
+    }
     // Create default usage group on first install
     const defaultGroup = await this.db.getRepository('aiApiUsageGroups').findOne({
       filter: { isDefault: true },
@@ -256,6 +307,15 @@ export class PluginAiApiServer extends Plugin {
     }
   }
 
+  private async cleanupResponseRecords(): Promise<void> {
+    try {
+      const deleted = await cleanupExpiredResponseRecords({ db: this.db });
+      if (deleted > 0) this.app.logger.info(`[ai-api] Cleaned up ${deleted} expired response records`);
+    } catch (error) {
+      this.app.logger.warn('[ai-api] Failed to clean up expired response records:', error);
+    }
+  }
+
   async afterEnable() {}
 
   async afterDisable() {}
@@ -266,6 +326,10 @@ export class PluginAiApiServer extends Plugin {
       clearInterval(this.gcInterval);
       this.gcInterval = null;
     }
+    if (this.responseCleanupInterval) {
+      clearInterval(this.responseCleanupInterval);
+      this.responseCleanupInterval = null;
+    }
     this.rateLimiter.clear();
   }
 }

package/src/server/resource/ai-api-config.ts

@@ -59,7 +59,8 @@ const aiApiConfigResource: ResourceOptions = {
     },
 
     async save(ctx, next) {
-      const values = ctx.action.params.values || (ctx.request.body as any) || {};
+      const values: Record<string, unknown> =
+        ctx.action.params.values || (ctx.request.body as Record<string, unknown>) || {};
       const repo = ctx.db.getRepository('aiApiConfig');
       let config = await repo.findOne();
 

package/src/server/routes/agent-completions.ts

@@ -104,6 +104,9 @@ export async function handleAgentCompletions(ctx: Context, plugin: PluginAiApiSe
   }
 
   // ─── Resolve model ─────────────────────────────────────────────────────────
+  // Agent mode runs the AI Employee pipeline, so virtual aliases ("auto") are intentionally
+  // not resolved here: capability-bucket routing is a direct-LLM concept. The model field
+  // selects the concrete model the employee uses.
   const resolved = await resolveModelString(ctx, body.model);
   if (!resolved) {
     ctx.status = 404;

package/src/server/routes/auth.ts

@@ -75,7 +75,7 @@ export async function authenticateBearer(ctx: Context): Promise<boolean> {
       return false;
     }
 
-    let decoded: { userId?: string | number; roleName?: string; temp?: boolean };
+    let decoded: { userId?: string | number; roleName?: string; temp?: boolean; jti?: string };
     try {
       decoded = await jwt.decode(token);
     } catch (e) {
@@ -90,6 +90,26 @@ export async function authenticateBearer(ctx: Context): Promise<boolean> {
       return false;
     }
 
+    // Enforce the token blacklist here as well. Revoked API keys are blocked by
+    // the core NocoBase auth path (Auth.checkToken), but this API-key fallback
+    // decodes the JWT directly and would otherwise keep accepting them.
+    if (jwt.blacklist) {
+      let blocked = false;
+      try {
+        blocked = await jwt.blacklist.has(decoded.jti ?? token);
+      } catch (err) {
+        ctx.log.error('AI API token blacklist check failed:', err);
+        ctx.status = 401;
+        ctx.body = toOpenAIError(401, 'Unable to verify API key status', 'server_error');
+        return false;
+      }
+      if (blocked) {
+        ctx.status = 401;
+        ctx.body = toOpenAIError(401, 'API key has been revoked', 'invalid_request_error', 'invalid_api_key');
+        return false;
+      }
+    }
+
     // This fallback is for API keys only. A normal login/OIDC token should have
     // been resolved by NocoBase auth middleware and must not be treated as the
     // member role merely because it has no roleName claim.

package/src/server/routes/chat-completions.ts

@@ -20,6 +20,7 @@ import {
   OpenAIToolCallChunk,
 } from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
+import { resolveVirtualModel, respondVirtualModelUnavailable } from '../utils/virtual-models';
 import {
   createRequestAbortController,
   isClientDisconnected,
@@ -96,8 +97,17 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
 
   const stream = isStreamingRequested(body.stream);
 
-  // ─── Resolve model string against DB ───
-  const resolved = await resolveModelString(ctx, body.model);
+  // ─── Resolve model string against DB (virtual alias first, then concrete) ───
+  const virtual = await resolveVirtualModel(ctx, body.model, body, 'chat');
+  if (virtual?.status === 'unavailable') {
+    respondVirtualModelUnavailable(ctx, virtual);
+    return;
+  }
+  if (virtual?.status === 'resolved') {
+    ctx.state.aiApiVirtualModel = virtual.virtualModel;
+    ctx.state.aiApiRoutingReason = virtual.reason;
+  }
+  const resolved = virtual?.resolved ?? (await resolveModelString(ctx, body.model));
   if (!resolved) {
     ctx.status = 404;
     ctx.body = toOpenAIError(
@@ -236,7 +246,7 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
         chatModel,
         langchainMessages,
         completionId,
-        body.model,
+        `${service.name}/${modelId}`,
         providerRequestParameters,
       );
     } else {
@@ -246,7 +256,7 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
         chatModel,
         langchainMessages,
         completionId,
-        body.model,
+        `${service.name}/${modelId}`,
         providerRequestParameters,
       );
     }
@@ -722,7 +732,7 @@ function describeImageUrlProblem(imageUrl: unknown): string | undefined {
  * A LangChain message content value: plain text, or an array of content blocks
  * (`{type:'text'}`, `{type:'image_url'}`, ...) for multimodal requests.
  */
-type MessageContent = string | Record<string, unknown>[];
+export type MessageContent = string | Record<string, unknown>[];
 
 /**
  * Normalize an OpenAI `message.content` into something LangChain accepts.
@@ -763,7 +773,7 @@ export function normalizeMessageContent(content: unknown): MessageContent {
  * block (e.g. a `file_url` becomes a `file` block, which may then be converted
  * to images by the PDF processor).
  */
-async function processMessageContentFileBlocks(
+export async function processMessageContentFileBlocks(
   content: unknown,
   ctx: Context,
   plugin: PluginAiApiServer,
@@ -807,7 +817,21 @@ async function processFileBlockChain(
   return next;
 }
 
-const GATEWAY_MANAGED_PARAMETERS = new Set(['model', 'messages', 'prompt', 'tools', 'tool_choice', 'stream', 'n']);
+const GATEWAY_MANAGED_PARAMETERS = new Set([
+  'model',
+  'messages',
+  'prompt',
+  'tools',
+  'tool_choice',
+  'stream',
+  'n',
+  // Responses API specific fields that should not be passed to providers
+  'input',
+  'previous_response_id',
+  'store',
+  'truncation',
+  'metadata',
+]);
 
 export function getProviderRequestParameters(body: Record<string, unknown>): Record<string, unknown> {
   return Object.fromEntries(
@@ -836,7 +860,7 @@ export function applyProviderRequestParameters(chatModel: unknown, parameters: R
   model.modelKwargs = { ...modelKwargs, ...parameters };
 }
 
-function bindRequestTools(
+export function bindRequestTools(
   chatModel: any,
   tools: unknown,
   toolChoice: unknown,
@@ -865,7 +889,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-function normalizeToolCalls(value: unknown): OpenAIToolCall[] | undefined {
+export function normalizeToolCalls(value: unknown): OpenAIToolCall[] | undefined {
   if (!Array.isArray(value) || value.length === 0) return undefined;
   return value.map((call: any) => ({
     id: String(call.id || ''),
@@ -877,7 +901,7 @@ function normalizeToolCalls(value: unknown): OpenAIToolCall[] | undefined {
   }));
 }
 
-function normalizeToolCallChunks(value: unknown): OpenAIToolCallChunk[] {
+export function normalizeToolCallChunks(value: unknown): OpenAIToolCallChunk[] {
   if (!Array.isArray(value)) return [];
   return value.map((call: any, fallbackIndex) => ({
     index: typeof call.index === 'number' ? call.index : fallbackIndex,

package/src/server/routes/completions.ts

@@ -16,6 +16,7 @@ import {
   toOpenAIUsageChunk,
 } from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
+import { resolveVirtualModel, respondVirtualModelUnavailable } from '../utils/virtual-models';
 import { enforceModelAccess } from '../utils/user-permissions';
 import {
   createRequestAbortController,
@@ -70,7 +71,16 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
   const stream = isStreamingRequested(body.stream);
 
   // ─── Resolve model string against DB ───
-  const resolved = await resolveModelString(ctx, body.model);
+  const virtual = await resolveVirtualModel(ctx, body.model, body, 'chat');
+  if (virtual?.status === 'unavailable') {
+    respondVirtualModelUnavailable(ctx, virtual);
+    return;
+  }
+  if (virtual?.status === 'resolved') {
+    ctx.state.aiApiVirtualModel = virtual.virtualModel;
+    ctx.state.aiApiRoutingReason = virtual.reason;
+  }
+  const resolved = virtual?.resolved ?? (await resolveModelString(ctx, body.model));
   if (!resolved) {
     ctx.status = 404;
     ctx.body = toOpenAIError(
@@ -124,7 +134,8 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
 
     if (body.temperature !== undefined) modelOptions.temperature = body.temperature;
     if (body.top_p !== undefined) modelOptions.topP = body.top_p;
-    if (body.max_tokens !== undefined) modelOptions.maxTokens = body.max_tokens;
+    if (body.max_completion_tokens !== undefined) modelOptions.maxTokens = body.max_completion_tokens;
+    else if (body.max_tokens !== undefined) modelOptions.maxTokens = body.max_tokens;
     if (body.stop !== undefined) modelOptions.stop = body.stop;
 
     // ─── Convert prompt to message tuple ───
@@ -142,6 +153,7 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
       serviceName: service.name,
       modelId,
       messages,
+      maxCompletionTokens: body.max_completion_tokens,
       maxTokens: body.max_tokens,
     });
     await prepareLlmBilling(ctx, resolved);
@@ -169,7 +181,7 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
         chatModel,
         langchainMessages,
         completionId,
-        body.model,
+        `${service.name}/${modelId}`,
         body.stream_options,
         providerRequestParameters,
       );
@@ -179,7 +191,7 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
         chatModel,
         langchainMessages,
         completionId,
-        body.model,
+        `${service.name}/${modelId}`,
         providerRequestParameters,
       );
     }

package/src/server/routes/embeddings.ts

@@ -10,10 +10,12 @@
 import { Context } from '@nocobase/actions';
 import { toOpenAIError, toOpenAIEmbeddingsResponse } from '../utils/openai-format';
 import { resolveModelString } from '../utils/resolve-service';
+import { resolveVirtualModel, respondVirtualModelUnavailable } from '../utils/virtual-models';
 import { enforceModelAccess } from '../utils/user-permissions';
 import { getAiApiConfig } from '../utils/request-cache';
-import { setAiApiUsageUnavailable } from '../usage';
+import { setAiApiUsageResult } from '../usage';
 import type PluginAiApiServer from '../plugin';
+import { markLlmProviderAttempted, prepareLlmBilling, AiApiQuotaError } from '../billing';
 
 /**
  * POST /api/ai-llm/v1/embeddings
@@ -89,7 +91,16 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
   }
 
   // ─── Resolve model ────────────────────────────────────────────────────────
-  const resolved = await resolveModelString(ctx, body.model);
+  const virtual = await resolveVirtualModel(ctx, body.model, body, 'embedding');
+  if (virtual?.status === 'unavailable') {
+    respondVirtualModelUnavailable(ctx, virtual);
+    return;
+  }
+  if (virtual?.status === 'resolved') {
+    ctx.state.aiApiVirtualModel = virtual.virtualModel;
+    ctx.state.aiApiRoutingReason = virtual.reason;
+  }
+  const resolved = virtual?.resolved ?? (await resolveModelString(ctx, body.model));
   if (!resolved) {
     ctx.status = 404;
     ctx.body = toOpenAIError(
@@ -156,7 +167,12 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
     return;
   }
 
+  // ─── Prepare billing/quota after access checks ────────────────────────────
+  // Running this after service.enabled and enforceModelAccess avoids a needless
+  // reserve/release round-trip on every rejected request.
+
   try {
+    await prepareLlmBilling(ctx, resolved);
     // ─── Instantiate and call the embedding provider ──────────────────────
     const EmbeddingClass = providerMeta.embedding;
     const embeddingProvider = new EmbeddingClass({
@@ -168,13 +184,22 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
     // createEmbedding() returns a LangChain EmbeddingsInterface.
     // embedDocuments() accepts string[] and returns number[][] (one vector per input).
     const embeddingModel = embeddingProvider.createEmbedding();
+    markLlmProviderAttempted(ctx);
     const vectors: number[][] = await embeddingModel.embedDocuments(inputs);
 
+    // Estimate input tokens: average 4 chars per token (conservative).
+    const estimatedInputTokens = Math.ceil(inputs.reduce((sum, s) => sum + s.length, 0) / 4);
+    const usage = {
+      prompt_tokens: estimatedInputTokens,
+      completion_tokens: 0,
+      total_tokens: estimatedInputTokens,
+    };
+    setAiApiUsageResult(ctx, usage);
+
     ctx.status = 200;
     ctx.set('Content-Type', 'application/json');
-    setAiApiUsageUnavailable(ctx);
     ctx.body = toOpenAIEmbeddingsResponse({
-      model: body.model,
+      model: `${service.name}/${modelId}`,
       embeddings: vectors,
       // LangChain's EmbeddingsInterface does not expose token counts.
       promptTokens: null,
@@ -182,8 +207,19 @@ export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer)
   } catch (err) {
     ctx.log.error('AI API embeddings error:', err);
     if (!ctx.res.headersSent) {
-      ctx.status = 500;
-      ctx.body = toOpenAIError(500, err.message || 'Failed to generate embeddings', 'server_error');
+      const isQuotaError = err instanceof AiApiQuotaError;
+      ctx.status = isQuotaError ? 429 : 500;
+      if (isQuotaError) ctx.set('X-RateLimit-Reason', err.code);
+      ctx.body = toOpenAIError(
+        ctx.status,
+        getErrorMessage(err, 'Failed to generate embeddings'),
+        isQuotaError ? 'quota_error' : 'server_error',
+        isQuotaError ? err.code : undefined,
+      );
     }
   }
 }
+
+function getErrorMessage(error: unknown, fallback: string) {
+  return error instanceof Error && error.message ? error.message : fallback;
+}