Ai
人工智能概述
Nebutra 内置的 AI 功能——基于 OpenAI 和 OpenRouter 的聊天补全、嵌入向量和语义搜索。
包含的功能
Nebutra 通过 @nebutra/agents 开箱即用地提供 AI 功能。该包是 Vercel AI SDK 的轻量封装，自动集成了租户上下文、限流和用量计量。
每个租户可使用以下功能：
| 功能 | 描述 | 功能标志 |
|---|---|---|
| 聊天补全 | 流式和非流式 LLM 响应 | ai.chat |
| 嵌入向量 | 用于语义搜索和 RAG 的向量表示 | ai.embeddings |
| 图像分析 | 支持视觉能力的模型（GPT-5） | ai.chat |
| 模型选择 | 每租户模型覆盖（企业版） | ai.model_selection |
架构
请求经过 API 网关，在代理到底层模型供应商之前自动完成鉴权、限流和计量：
客户端应用
│
▼
POST /api/v1/ai/chat (API 网关 — Hono)
│
├─ 鉴权检查（API Key）
├─ 功能标志检查（ai.chat）
├─ 限流（按租户，@nebutra/rate-limit）
│
▼
@nebutra/agents (Vercel AI SDK v6 封装)
│
├─ OpenAI （默认）
└─ OpenRouter （多模型：Claude、Llama、Mistral……）
│
▼
响应 / SSE 流
│
▼
@nebutra/metering （消耗的 Token → 计费）
│
▼
pgvector（仅嵌入向量） （PostgreSQL 向量存储）支持的模型
| 模型 | 上下文窗口 | 适用场景 |
|---|---|---|
gpt-5.5 | ~400 k+ | 旗舰推理、视觉、编程 |
gpt-5.4-mini | ~400 k+ | 快速、低成本任务 |
text-embedding-3-small | — | 嵌入向量（1536 维） |
text-embedding-3-large | — | 高精度嵌入向量（3072 维） |
模型 id 以 models.dev 为准。业务代码优先用 @nebutra/ai-providers 的语义档位（flagship / fast），避免手写过期字符串。
| 模型 | 供应商 | 备注 |
|---|---|---|
anthropic/claude-sonnet-4.6 | Anthropic | 默认旗舰推理 |
anthropic/claude-haiku-4.5 | Anthropic | 快速 / 低成本 |
openai/gpt-5.5 | OpenAI | OpenRouter 上的 OpenAI 旗舰 |
google/gemini-3.1-pro-preview | 长上下文旗舰 | |
google/gemini-3.5-flash | 快速多模态 |
将完整模型标识符传入 streamText / generateText。实时目录见 models.dev / OpenRouter 模型页。
功能标志
AI 功能默认关闭，需要按租户启用。标志在 API 网关发起任何模型调用之前检查——如果标志关闭，不会消耗任何 Token。
// 以编程方式为租户启用 AI
import { setFeatureFlag } from "@nebutra/preset";
await setFeatureFlag("org_123", "ai.chat", true);
await setFeatureFlag("org_123", "ai.embeddings", true);也可以在控制台的 组织 → 功能 中切换标志。
环境变量
将以下变量添加到 .env（或 Vercel 环境变量）：
# 必填：至少提供一个供应商密钥
OPENAI_API_KEY=""
# 可选：通过 OpenRouter 启用多模型路由
OPENROUTER_API_KEY=""
# 未在请求中指定模型时使用的默认模型
AI_DEFAULT_MODEL="gpt-5.4-mini"
# 可选：覆盖默认嵌入模型
AI_EMBEDDING_MODEL="text-embedding-3-small"切勿将 OPENAI_API_KEY 或 OPENROUTER_API_KEY 暴露给客户端。所有模型调用必须通过 API 网关进行。
用量与配额
Token 消耗通过 @nebutra/metering 自动计量，并计入租户的 API 配额。可以通过代码或控制台查看当前用量：
import { getMetering, COMMON_METERS } from "@nebutra/metering";
const metering = await getMetering();
const quota = await metering.getQuota("org_123", "ai_tokens");
// → { limit: 5000000, used: 1243000, remaining: 3757000, percentage: 0.249 }各套餐配额限制：
| 套餐 | 每月 AI Token 数 |
|---|---|
| FREE | 100,000 |
| PRO | 5,000,000 |
| ENTERPRISE | 自定义 |
快速使用示例
import { streamText, generateText, embed } from "@nebutra/agents";
// 流式聊天（SSE）
const result = await streamText({
model: "gpt-5.5",
messages: [
{ role: "system", content: "你是一个有帮助的助手。" },
{ role: "user", content: userMessage },
],
tenantId,
});
// 非流式
const { text } = await generateText({
model: "gpt-5.4-mini",
prompt: "总结以下内容：" + content,
tenantId,
});
// 嵌入向量
const { embedding } = await embed({
model: "text-embedding-3-small",
value: "需要嵌入的文本",
tenantId,
});相关文档
How is this guide?
在 GitHub 上编辑此页面
最后更新于