plugin-ai-api 1.0.15 → 1.0.21

package/src/locale/zh-CN.json

@@ -1,10 +1,105 @@
-{
-  "AI API Gateway": "AI API 网关",
-  "Configuration": "配置",
-  "Default AI Employee": "默认 AI 员工",
-  "Enabled LLM Services": "已启用 LLM 服务",
-  "Rate Limit": "速率限制",
-  "Save Configuration": "保存配置",
-  "Configuration saved": "配置已保存",
-  "Failed to save configuration": "保存配置失败"
-}
+{
+  "AI API Gateway": "AI API 网关",
+  "Configuration": "配置",
+  "Default AI Employee": "默认 AI 员工",
+  "Enabled LLM Services": "已启用 LLM 服务",
+  "Rate Limit": "速率限制",
+  "Save Configuration": "保存配置",
+  "Configuration saved": "配置已保存",
+  "Failed to save configuration": "保存配置失败",
+  "API mode": "API 模式",
+  "Direct LLM": "直接 LLM",
+  "AI Employee agent": "AI 员工代理",
+  "Default LLM service": "默认 LLM 服务",
+  "Enable user quotas": "启用用户配额",
+  "Default reserved output tokens": "默认预留输出令牌数",
+  "Refresh": "刷新",
+  "Model pricing": "模型定价",
+  "User quotas": "用户配额",
+  "Usage": "用量",
+  "LLM service": "LLM 服务",
+  "Model": "模型",
+  "Input price / 1M": "输入价格 / 百万令牌",
+  "Output price / 1M": "输出价格 / 百万令牌",
+  "Fixed request cost": "每次请求固定费用",
+  "Currency": "货币",
+  "Status": "状态",
+  "Enabled": "已启用",
+  "Disabled": "已禁用",
+  "Actions": "操作",
+  "Edit": "编辑",
+  "Delete": "删除",
+  "Delete this price?": "删除此价格？",
+  "Add price": "添加价格",
+  "Edit price": "编辑价格",
+  "Effective from": "生效时间",
+  "Effective to": "失效时间",
+  "Notes": "备注",
+  "Saved successfully": "保存成功",
+  "Deleted successfully": "删除成功",
+  "User": "用户",
+  "Period": "周期",
+  "Request limit": "请求限制",
+  "Token limit": "令牌限制",
+  "Cost limit": "费用限制",
+  "Timezone": "时区",
+  "Unlimited": "无限制",
+  "Add quota": "添加配额",
+  "Edit quota": "编辑配额",
+  "Delete this quota?": "删除此配额？",
+  "Daily": "每日",
+  "Monthly": "每月",
+  "Reject unpriced models": "拒绝未定价模型",
+  "Missing usage behavior": "缺少用量时的行为",
+  "Use reserved estimate": "使用预留估算",
+  "Allow without token charge": "允许且不计令牌",
+  "Started at": "开始时间",
+  "Requested model": "请求模型",
+  "Resolved service": "解析后的服务",
+  "Resolved model": "解析后的模型",
+  "Input tokens": "输入令牌",
+  "Output tokens": "输出令牌",
+  "Total tokens": "总令牌",
+  "Cost": "费用",
+  "Cost status": "费用状态",
+  "Request ID": "请求 ID",
+  "Failed to load models": "加载模型失败",
+  "Select a model": "选择模型",
+  "Select an AI Employee": "选择 AI 员工",
+  "Usage guide": "使用指南",
+  "OpenAI-compatible endpoint": "OpenAI 兼容端点",
+  "Base URL": "基础 URL",
+  "Use a NocoBase API key as the Bearer token.": "使用 NocoBase API 密钥作为 Bearer Token。",
+  "List available models": "列出可用模型",
+  "Send a chat completion": "发送聊天补全请求",
+  "Usage filters": "用量筛选",
+  "Time range": "时间范围",
+  "User ID": "用户 ID",
+  "Succeeded": "成功",
+  "Failed": "失败",
+  "Started": "已开始",
+  "Apply filters": "应用筛选",
+  "Reset": "重置",
+  "Requests": "请求数",
+  "Total cost": "总费用",
+  "Usage records": "用量记录",
+  "Model metadata": "模型元数据",
+  "Add override": "添加覆盖",
+  "Edit override": "编辑覆盖",
+  "Delete this override?": "确认删除此覆盖？",
+  "Context window": "上下文窗口",
+  "Max completion tokens": "最大输出 token 数",
+  "Owned by": "所属方",
+  "Display name": "显示名称",
+  "Description": "描述",
+  "Leave empty to not override": "留空则不覆盖",
+  "Total input + output token capacity reported to clients.": "返回给客户端的输入+输出 token 总容量。",
+  "Maximum output tokens reported to clients.": "返回给客户端的最大输出 token 数。",
+  "AI API": "AI API",
+  "Allow this role to use the AI API": "允许此角色使用 AI API",
+  "Allow all AI Employees": "允许所有 AI 员工",
+  "Select which AI Employees this role may use:": "选择此角色可使用的 AI 员工：",
+  "Select allowed AI Employees": "选择允许的 AI 员工",
+  "Max request body size (MB)": "请求体大小上限（MB）",
+  "Raise this to accept inline base64 images. Base64 adds about 33% to the original file size.": "调高此值以接收内联 base64 图片。base64 编码会使体积增加约 33%。"
+}

package/src/server/__tests__/app-observability.test.ts

@@ -0,0 +1,98 @@
+import type { Context } from '@nocobase/actions';
+import {
+  addAiApiUsage,
+  finishAiApiObservation,
+  markAiApiFirstProviderOutput,
+  startAiApiObservation,
+} from '../utils/app-observability';
+
+const CONTRACT_SYMBOL = Symbol.for('nocobase.app-observability.contract');
+
+function createContext(contract?: object): Context {
+  const app = {
+    logger: { warn: vi.fn() },
+    ...(contract ? { [CONTRACT_SYMBOL]: contract } : {}),
+  };
+  return { app, state: {} } as unknown as Context;
+}
+
+describe('AI API app observability bridge', () => {
+  it('is a no-op when observability is absent', () => {
+    const ctx = createContext();
+    expect(() => {
+      startAiApiObservation(ctx, {
+        service: 'llm.chat',
+        operation: '/chat/completions',
+        streaming: true,
+        mode: 'llm',
+      });
+      markAiApiFirstProviderOutput(ctx);
+      addAiApiUsage(ctx, { prompt_tokens: 2, completion_tokens: 3 });
+      finishAiApiObservation(ctx, { status: 'succeeded' });
+    }).not.toThrow();
+  });
+
+  it('records TTFT, normalized usage and finalizes exactly once', () => {
+    const handle = {
+      markFirstByte: vi.fn(),
+      addInputTokens: vi.fn(),
+      addOutputTokens: vi.fn(),
+      finish: vi.fn(),
+    };
+    const start = vi.fn(() => handle);
+    const ctx = createContext({ start });
+
+    startAiApiObservation(ctx, {
+      service: 'llm.agent',
+      operation: '/chat/completions',
+      streaming: true,
+      model: 'service/model',
+      mode: 'agent',
+    });
+    markAiApiFirstProviderOutput(ctx);
+    addAiApiUsage(ctx, { prompt_tokens: 11, completion_tokens: 7 });
+    finishAiApiObservation(ctx, { status: 'succeeded' });
+    finishAiApiObservation(ctx, { status: 'failed' });
+
+    expect(start).toHaveBeenCalledWith(
+      expect.objectContaining({
+        service: 'llm.agent',
+        streaming: true,
+        attributes: expect.objectContaining({ mode: 'agent', model: 'service/model' }),
+      }),
+    );
+    expect(handle.markFirstByte).toHaveBeenCalledTimes(1);
+    expect(handle.addInputTokens).toHaveBeenCalledWith(11);
+    expect(handle.addOutputTokens).toHaveBeenCalledWith(7);
+    expect(handle.finish).toHaveBeenCalledTimes(1);
+    expect(handle.finish).toHaveBeenCalledWith({ status: 'succeeded' });
+  });
+
+  it('fails open when contract callbacks throw', () => {
+    const ctx = createContext({
+      start: () => ({
+        markFirstByte: () => {
+          throw new Error('ttft failed');
+        },
+        addInputTokens: () => {
+          throw new Error('tokens failed');
+        },
+        addOutputTokens: () => {},
+        finish: () => {
+          throw new Error('finish failed');
+        },
+      }),
+    });
+    expect(() => {
+      startAiApiObservation(ctx, {
+        service: 'llm.completion',
+        operation: '/completions',
+        streaming: true,
+        mode: 'llm',
+      });
+      markAiApiFirstProviderOutput(ctx);
+      addAiApiUsage(ctx, { prompt_tokens: 1, completion_tokens: null });
+      finishAiApiObservation(ctx, { status: 'failed', errorCode: 'stream_error' });
+    }).not.toThrow();
+  });
+});

package/src/server/__tests__/billing-quota.test.ts

@@ -0,0 +1,134 @@
+import type { Context } from '@nocobase/actions';
+import { createMockDatabase, type Database } from '@nocobase/database';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { AiApiQuotaError, finalizeLlmBilling, markLlmProviderAttempted, prepareLlmBilling } from '../billing';
+
+describe('AI API user quota reservation', () => {
+  let db: Database;
+
+  beforeEach(async () => {
+    db = await createMockDatabase();
+    db.collection({
+      name: 'aiApiConfig',
+      fields: [
+        { name: 'quotaEnabled', type: 'boolean' },
+        { name: 'defaultReservationOutputTokens', type: 'integer' },
+      ],
+    });
+    db.collection({
+      name: 'aiApiModelPrices',
+      fields: [
+        { name: 'llmService', type: 'string' },
+        { name: 'model', type: 'string' },
+        { name: 'enabled', type: 'boolean' },
+        { name: 'currency', type: 'string' },
+        { name: 'inputPricePerMillionTokens', type: 'decimal', precision: 20, scale: 10 },
+        { name: 'outputPricePerMillionTokens', type: 'decimal', precision: 20, scale: 10 },
+        { name: 'fixedCostPerRequest', type: 'decimal', precision: 20, scale: 10 },
+        { name: 'effectiveFrom', type: 'datetimeTz' },
+        { name: 'effectiveTo', type: 'datetimeTz' },
+      ],
+    });
+    db.collection({
+      name: 'aiApiUserQuotaPolicies',
+      fields: [
+        { name: 'userId', type: 'bigInt' },
+        { name: 'enabled', type: 'boolean' },
+        { name: 'periodType', type: 'string' },
+        { name: 'timezone', type: 'string' },
+        { name: 'requestLimit', type: 'bigInt' },
+        { name: 'totalTokenLimit', type: 'bigInt' },
+        { name: 'costLimit', type: 'decimal', precision: 20, scale: 8 },
+        { name: 'currency', type: 'string' },
+        { name: 'rejectUnpricedModel', type: 'boolean' },
+        { name: 'missingUsageBehavior', type: 'string' },
+      ],
+    });
+    db.collection({
+      name: 'aiApiUserQuotaBuckets',
+      fields: [
+        { name: 'policyId', type: 'bigInt' },
+        { name: 'userId', type: 'bigInt' },
+        { name: 'periodStart', type: 'datetimeTz' },
+        { name: 'periodEnd', type: 'datetimeTz' },
+        { name: 'requestCount', type: 'bigInt' },
+        { name: 'totalTokens', type: 'bigInt' },
+        { name: 'cost', type: 'decimal', precision: 20, scale: 8 },
+        { name: 'reservedRequests', type: 'bigInt' },
+        { name: 'reservedTokens', type: 'bigInt' },
+        { name: 'reservedCost', type: 'decimal', precision: 20, scale: 8 },
+      ],
+      indexes: [{ fields: ['policyId', 'periodStart'], unique: true }],
+    });
+    await db.sync({ force: true });
+    await db.getRepository('aiApiConfig').create({
+      values: { quotaEnabled: true, defaultReservationOutputTokens: 100 },
+    });
+    await db.getRepository('aiApiModelPrices').create({
+      values: {
+        llmService: 'service-a',
+        model: 'model-a',
+        enabled: true,
+        currency: 'USD',
+        inputPricePerMillionTokens: '5',
+        outputPricePerMillionTokens: '15',
+        fixedCostPerRequest: '0',
+        effectiveFrom: new Date('2020-01-01T00:00:00Z'),
+      },
+    });
+    await db.getRepository('aiApiUserQuotaPolicies').create({
+      values: {
+        userId: 7,
+        enabled: true,
+        periodType: 'monthly',
+        timezone: 'UTC',
+        requestLimit: 1,
+        totalTokenLimit: 1000,
+        costLimit: '10',
+        currency: 'USD',
+        rejectUnpricedModel: true,
+        missingUsageBehavior: 'use_reserved',
+      },
+    });
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  function context(): Context {
+    return {
+      db,
+      request: { body: { messages: [{ role: 'user', content: 'hello' }], max_tokens: 100 } },
+      state: { currentUser: { id: 7 } },
+    } as unknown as Context;
+  }
+
+  const resolved = {
+    service: { name: 'service-a', provider: 'custom-llm' },
+    modelId: 'model-a',
+  };
+
+  it('reserves atomically and reconciles actual provider usage', async () => {
+    const first = context();
+    await prepareLlmBilling(first, resolved);
+
+    const competing = context();
+    await expect(prepareLlmBilling(competing, resolved)).rejects.toMatchObject<Partial<AiApiQuotaError>>({
+      code: 'request_quota_exceeded',
+    });
+
+    markLlmProviderAttempted(first);
+    const finalized = await finalizeLlmBilling(
+      first,
+      { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+      true,
+    );
+    expect(finalized).toMatchObject({ estimatedCost: '0.00012500', costStatus: 'calculated' });
+
+    const bucket = await db.getRepository('aiApiUserQuotaBuckets').findOne();
+    expect(String(bucket?.get('requestCount'))).toBe('1');
+    expect(String(bucket?.get('totalTokens'))).toBe('15');
+    expect(String(bucket?.get('reservedRequests'))).toBe('0');
+  });
+});

package/src/server/__tests__/billing.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { calculateLlmCost, type PriceSnapshot } from '../billing';
+
+function price(values: Partial<PriceSnapshot> = {}): PriceSnapshot {
+  return {
+    id: 1,
+    currency: 'USD',
+    inputPricePerMillionTokens: '5.0000000000',
+    outputPricePerMillionTokens: '15.0000000000',
+    fixedCostPerRequest: '0.0000000000',
+    ...values,
+  };
+}
+
+describe('AI API LLM cost calculation', () => {
+  it('calculates input and output token cost using decimal arithmetic', () => {
+    expect(calculateLlmCost(10_000, 2_000, price())).toBe('0.08000000');
+  });
+
+  it('includes a fixed per-request cost', () => {
+    expect(calculateLlmCost(0, 0, price({ fixedCostPerRequest: '0.1250000000' }))).toBe('0.12500000');
+  });
+
+  it('rounds to eight decimal places without floating-point drift', () => {
+    expect(
+      calculateLlmCost(
+        1,
+        1,
+        price({ inputPricePerMillionTokens: '0.1000000000', outputPricePerMillionTokens: '0.2000000000' }),
+      ),
+    ).toBe('0.00000030');
+  });
+});

package/src/server/__tests__/models.test.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 { describe, expect, it } from 'vitest';
+import { buildModelObject } from '../routes/models';
+
+const CREATED = 1_700_000_000;
+
+describe('buildModelObject', () => {
+  it('returns the base OpenAI model shape with no override', () => {
+    const model = buildModelObject('svc/gpt-4o', CREATED, 'My Service');
+    expect(model).toEqual({
+      id: 'svc/gpt-4o',
+      object: 'model',
+      created: CREATED,
+      owned_by: 'My Service',
+    });
+    // No override → no context_window / active field is added.
+    expect(model).not.toHaveProperty('context_window');
+    expect(model).not.toHaveProperty('active');
+  });
+
+  it('emits context window under both context_window and context_length', () => {
+    const model = buildModelObject('svc/m', CREATED, 'Svc', { contextWindow: 100_000 });
+    expect(model.context_window).toBe(100_000);
+    expect(model.context_length).toBe(100_000);
+  });
+
+  it('overrides owned_by, display name and description', () => {
+    const model = buildModelObject('svc/m', CREATED, 'Svc', {
+      ownedByOverride: 'Acme',
+      displayName: 'Acme Turbo',
+      description: 'Fast model',
+    });
+    expect(model.owned_by).toBe('Acme');
+    expect(model.display_name).toBe('Acme Turbo');
+    expect(model.name).toBe('Acme Turbo');
+    expect(model.description).toBe('Fast model');
+  });
+
+  it('falls back to the service label when ownedByOverride is empty', () => {
+    const model = buildModelObject('svc/m', CREATED, 'Svc', { ownedByOverride: '' });
+    expect(model.owned_by).toBe('Svc');
+  });
+
+  it('emits max_completion_tokens only when positive', () => {
+    expect(buildModelObject('svc/m', CREATED, 'Svc', { maxCompletionTokens: 4096 }).max_completion_tokens).toBe(4096);
+    expect(buildModelObject('svc/m', CREATED, 'Svc', { maxCompletionTokens: 0 })).not.toHaveProperty(
+      'max_completion_tokens',
+    );
+    expect(buildModelObject('svc/m', CREATED, 'Svc', { maxCompletionTokens: null })).not.toHaveProperty(
+      'max_completion_tokens',
+    );
+  });
+
+  it('ignores non-positive or non-integer context windows', () => {
+    expect(buildModelObject('svc/m', CREATED, 'Svc', { contextWindow: 0 })).not.toHaveProperty('context_window');
+    expect(buildModelObject('svc/m', CREATED, 'Svc', { contextWindow: -5 })).not.toHaveProperty('context_window');
+    expect(buildModelObject('svc/m', CREATED, 'Svc', { contextWindow: null })).not.toHaveProperty('context_window');
+  });
+
+  it('surfaces active flag whenever an override row exists', () => {
+    expect(buildModelObject('svc/m', CREATED, 'Svc', { enabled: true }).active).toBe(true);
+    expect(buildModelObject('svc/m', CREATED, 'Svc', { enabled: false }).active).toBe(false);
+    // Override present with enabled undefined → treated as active.
+    expect(buildModelObject('svc/m', CREATED, 'Svc', { contextWindow: 10 }).active).toBe(true);
+  });
+});