Skip to Content
文档Aimodule功能配置

环境配置

AI Module 提供了两种配置方式：环境变量配置（适合静态配置）和运行时 API 配置（支持动态热更新）。支持通义千问和 DeepSeek 两个 AI 服务商。

运行时配置 API（推荐）

从 v1.0.3 版本开始，AI Module 支持通过代码动态配置，无需重启即可更新 AI 行为参数。

核心配置接口

interface AIModuleConfig {
  // AI 核心参数
  systemPrompt?: string;          // 系统提示词
  temperature?: number;            // 温度 (0-2)
  maxTokens?: number;              // 最大输出 tokens
  topP?: number;                   // 核采样 (0-1)
  topK?: number;                   // Top-K 采样
  presencePenalty?: number;        // 存在性惩罚 (-2 to 2)
  frequencyPenalty?: number;       // 频率惩罚 (-2 to 2)
 
  // 功能开关
  enableTools?: boolean;           // 是否启用工具调用
  enableEmbeddings?: boolean;      // 是否启用向量嵌入
 
  // 模型配置
  defaultProvider?: string;        // 默认提供商 (qwen, openai, anthropic)
  defaultModel?: string;           // 默认模型
  defaultEmbeddingModel?: string;  // 默认嵌入模型
}

初始化时配置

在创建 AI Module 实例时传入配置：

import { EntityAIModule } from '@scenemesh/entity-engine-aimodule';
 
// 创建带有自定义配置的 AI Module
const aiModule = new EntityAIModule({
  systemPrompt: '你是一个专业的数据分析助手...',
  temperature: 0.8,
  maxTokens: 2000,
  enableTools: true,
  defaultProvider: 'qwen',
  defaultModel: 'qwen-plus'
});
 
// 在 Entity Engine 中使用
const init = new EnginePrimitiveInitializer({
  models,
  views,
  modules: [aiModule]
});

运行时热更新配置

无需重启应用即可动态更新配置：

import { EntityAIModule } from '@scenemesh/entity-engine-aimodule';
 
// 获取 AI Module 实例
const aiModule = EntityAIModule.getInstance();
 
// 更新配置（部分更新）
aiModule.updateConfig({
  temperature: 0.9,
  maxTokens: 3000
});
 
// 获取当前有效配置
const currentConfig = aiModule.getEffectiveConfig();
console.log('当前配置:', currentConfig);
 
// 获取运行时配置（仅用户设置的部分）
const runtimeConfig = aiModule.getRuntimeConfig();
console.log('运行时配置:', runtimeConfig);

配置优先级

配置的优先级从高到低为：

  1. 请求参数（单次请求临时覆盖）
  2. 运行时配置（通过 updateConfig() 设置）
  3. 初始化配置（构造函数传入）
  4. 环境变量（.env 文件）
  5. 硬编码默认值

示例：

// 1. 初始化配置
const aiModule = new EntityAIModule({
  temperature: 0.7,  // 初始化配置
  maxTokens: 2000
});
 
// 2. 运行时更新（优先级更高）
aiModule.updateConfig({
  temperature: 0.9  // 覆盖初始化配置
});
 
// 3. 请求时覆盖（优先级最高）
await fetch('/api/ai/chat', {
  method: 'POST',
  body: JSON.stringify({
    messages: [...],
    temperature: 0.5,  // 此次请求使用 0.5，不影响全局配置
    maxTokens: 1000
  })
});

实际应用场景

场景 1：根据用户角色动态调整

function configureAIForUser(userRole: string) {
  const aiModule = EntityAIModule.getInstance();
 
  if (userRole === 'developer') {
    aiModule.updateConfig({
      systemPrompt: '你是一个代码助手，精通 TypeScript 和 React...',
      temperature: 0.3,  // 更精确的代码生成
      enableTools: true
    });
  } else if (userRole === 'analyst') {
    aiModule.updateConfig({
      systemPrompt: '你是一个数据分析专家...',
      temperature: 0.7,  // 更有创造性的分析
      maxTokens: 4000    // 支持更长的分析报告
    });
  }
}

场景 2：A/B 测试不同的提示词

async function runABTest() {
  const aiModule = EntityAIModule.getInstance();
 
  // 测试组 A
  aiModule.updateConfig({
    systemPrompt: '提示词版本 A...',
    temperature: 0.7
  });
  const resultA = await testAIPerformance();
 
  // 测试组 B
  aiModule.updateConfig({
    systemPrompt: '提示词版本 B...',
    temperature: 0.8
  });
  const resultB = await testAIPerformance();
 
  console.log('A/B 测试结果:', { resultA, resultB });
}

场景 3：根据业务模式动态配置

// 在管理后台提供配置界面
function updateAIConfig(formData: AIModuleConfig) {
  const aiModule = EntityAIModule.getInstance();
 
  // 保存到数据库
  await saveConfigToDatabase(formData);
 
  // 立即生效（无需重启）
  aiModule.updateConfig(formData);
 
  console.log('AI 配置已更新并生效');
}

配置参数说明

参数类型范围默认值说明
systemPromptstring-内置提示词系统级提示词，定义 AI 角色和行为
temperaturenumber0-20.7控制输出随机性，越低越确定
maxTokensnumber>04000最大输出 token 数量
topPnumber0-10.95核采样，控制输出多样性
topKnumber>0-Top-K 采样（部分模型支持）
presencePenaltynumber-2 to 20惩罚已出现的 token，鼓励新话题
frequencyPenaltynumber-2 to 20惩罚频繁出现的 token
enableToolsboolean-true是否启用工具调用（如实体查询）
enableEmbeddingsboolean-true是否启用向量嵌入功能
defaultProviderstringqwen/openai/anthropicqwen默认 AI 服务商
defaultModelstring-qwen-plus默认使用的模型
defaultEmbeddingModelstring--默认嵌入模型

注意事项

  • ✅ 线程安全：updateConfig() 是同步操作，立即生效
  • ✅ 部分更新：只需传入需要修改的字段，其他字段保持不变
  • ⚠️ 持久化：运行时配置不会自动持久化，重启后恢复为初始化配置
  • ⚠️ 全局影响：配置更新会影响所有后续请求（除非请求自带参数覆盖）

基础环境变量

AI服务商配置

至少需要配置一个AI服务商的API密钥：

# .env.local
 
# 通义千问配置
EEAI_QWEN_API_KEY=your-qwen-api-key
 
# DeepSeek配置  
EEAI_DEEPSEEK_API_KEY=your-deepseek-api-key

服务商选择

# 指定默认使用的AI服务商
EEAI_MODEL_PROVIDER=qwen
# 或
EEAI_MODEL_PROVIDER=deepseek

高级配置

自定义API地址

如果需要使用自定义的API端点：

# 通义千问自定义地址
EEAI_QWEN_BASE_URL=https://your-custom-qwen-endpoint.com
 
# DeepSeek自定义地址
EEAI_DEEPSEEK_BASE_URL=https://your-custom-deepseek-endpoint.com

模型配置

# 指定可用的文本模型（逗号分隔）
EEAI_TEXT_MODELS=qwen-turbo,qwen-plus,deepseek-chat
 
# 指定默认模型
EEAI_DEFAULT_MODEL=qwen-turbo

通义千问配置详解

获取API密钥

  1. 访问 阿里云百炼平台 
  2. 登录您的阿里云账号
  3. 创建应用并获取API密钥
  4. 确保账户有足够的调用额度

配置示例

# 通义千问完整配置
EEAI_QWEN_API_KEY=sk-your-qwen-api-key
EEAI_QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EEAI_MODEL_PROVIDER=qwen
EEAI_TEXT_MODELS=qwen-turbo,qwen-plus,qwen-max

支持的模型

  • qwen-turbo - 快速响应，适合日常对话
  • qwen-plus - 平衡性能，推荐使用
  • qwen-max - 最强性能，处理复杂任务

DeepSeek配置详解

获取API密钥

  1. 访问 DeepSeek开放平台 
  2. 注册并登录账号
  3. 在API密钥页面创建新的密钥
  4. 充值获取调用额度

配置示例

# DeepSeek完整配置
EEAI_DEEPSEEK_API_KEY=sk-your-deepseek-api-key
EEAI_DEEPSEEK_BASE_URL=https://api.deepseek.com
EEAI_MODEL_PROVIDER=deepseek
EEAI_TEXT_MODELS=deepseek-chat,deepseek-coder

支持的模型

  • deepseek-chat - 通用对话模型
  • deepseek-coder - 代码专用模型

多服务商配置

您可以同时配置多个服务商，系统会根据配置自动选择：

# 同时配置两个服务商
EEAI_QWEN_API_KEY=your-qwen-key
EEAI_DEEPSEEK_API_KEY=your-deepseek-key
 
# 设置首选服务商
EEAI_MODEL_PROVIDER=qwen
 
# 配置所有可用模型
EEAI_TEXT_MODELS=qwen-turbo,qwen-plus,deepseek-chat

配置验证

检查配置是否正确

在您的应用中，可以通过以下方式验证配置：

  1. 查看控制台日志 启动应用时查看是否有AI相关的错误信息

  2. 测试API连接 点击”智能填表”按钮，发送测试消息验证连接

  3. 检查网络请求 在浏览器开发工具的Network面板中查看API请求是否成功

常见配置错误

环境变量未生效

  • 确保.env.local文件在项目根目录
  • 重启开发服务器
  • 检查变量名拼写是否正确

API密钥无效

  • 验证密钥是否正确复制
  • 确认密钥未过期
  • 检查账户余额是否充足

网络连接问题

  • 确认网络可以访问AI服务商API
  • 检查防火墙设置
  • 验证自定义API地址是否正确

生产环境配置

安全考虑

# 生产环境配置示例
EEAI_QWEN_API_KEY=your-production-qwen-key
EEAI_MODEL_PROVIDER=qwen
EEAI_TEXT_MODELS=qwen-plus
 
# 不要在生产环境中启用调试
# AI_DEBUG=false

性能优化

  • 选择合适的模型（速度vs性能权衡）
  • 配置合理的超时时间
  • 考虑使用缓存机制

监控和日志

建议在生产环境中：

  • 监控API调用频率和成本
  • 设置调用量报警
  • 记录异常和错误日志

环境变量完整列表

变量名必需说明默认值
EEAI_QWEN_API_KEY条件必需*通义千问API密钥-
EEAI_DEEPSEEK_API_KEY条件必需*DeepSeek API密钥-
EEAI_MODEL_PROVIDER否默认AI服务商自动检测
EEAI_QWEN_BASE_URL否通义千问API地址https://dashscope.aliyuncs.com/compatible-mode/v1
EEAI_DEEPSEEK_BASE_URL否DeepSeek API地址https://api.deepseek.com
EEAI_TEXT_MODELS否可用文本模型列表基于配置的服务商自动检测

*至少需要配置一个AI服务商的API密钥

配置完成后，您可以开始使用智能表单功能了。

Last updated on
快速开始智能表单