autoAiWorkSys/docs/ai_service_unified.md

AI 服务统一说明

更新时间: 2025-12-27

---

统一后的 AI 服务架构

系统已完成 AI 服务的统一整理，现在只保留一个标准的 AI 服务实现。

---

文件位置

✅ 保留的文件（唯一 AI 服务实现）

核心服务：

• api/services/ai_service.js - AI 服务主文件（基于阿里云 Qwen 2.5）
• api/services/ai_call_recorder.js - AI 调用记录服务

导出管理：

• api/services/index.js - 服务统一导出

数据库层：

• api/model/ai_call_records.js - AI 调用记录模型

后台管理：

• api/controller_admin/ai_call_records.js - 后台管理 API

前端界面：

• admin/src/views/system/ai_call_records.vue - 管理界面
• admin/src/api/system/ai_call_records_server.js - API 服务

❌ 已删除的文件

• api/middleware/job/aiService.js - 已删除（内容已迁移到 services/ai_service.js）

---

使用方式

1. 直接引用（推荐）

const aiService = require('./services/ai_service');

// 使用 AI 服务
const result = await aiService.analyzeJob(jobInfo, resumeInfo);

2. 通过服务管理器

const { AIService } = require('./services');

// 使用 AI 服务
const result = await AIService.analyzeJob(jobInfo, resumeInfo);

---

AI 服务功能列表

核心方法

方法	说明	业务类型
callAPI(prompt, options)	基础 API 调用	自定义
analyzeJob(jobInfo, resumeInfo)	岗位智能筛选	job_analysis
generateChatContent(jobInfo, resumeInfo, chatType)	生成个性化聊天	chat_generation
analyzeResume(resumeText)	简历分析	resume_analysis
generateInterviewInvitation(jobInfo, chatHistory)	生成面试邀约	interview_invitation
identifyOutsourcingJob(jobInfo)	识别外包岗位	outsourcing_detection

辅助方法

方法	说明
recordAiCall(params)	记录 AI 调用
calculateCost(totalTokens)	计算调用费用

---

Token 自动记录

所有通过 callAPI() 方法的调用都会自动记录以下信息：

• Token 使用量：prompt_tokens, completion_tokens, total_tokens
• 成本信息：基于模型计算的费用
• 性能指标：响应时间（毫秒）
• 状态跟踪：成功/失败状态
• 业务关联：business_type, reference_id
• 请求追踪：完整的请求和响应内容

记录过程是异步非阻塞的，不会影响 AI 调用的主流程。

---

配置说明

环境变量

在 .env 文件中配置：

# 阿里云 DashScope API Key
AI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxx

# 模型选择（可选）
AI_MODEL=qwen-turbo  # qwen-turbo, qwen-plus, qwen-max, qwen-long

代码配置

// 在 config/config.js 中
module.exports = {
    ai: {
        apiKey: process.env.AI_API_KEY,
        model: process.env.AI_MODEL || 'qwen-turbo'
    }
}

---

模型选择

模型	速度	质量	成本	价格（元/1000 tokens）
qwen-turbo	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	¥0.003
qwen-plus	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	¥0.004
qwen-max	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	¥0.12
qwen-long	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	-

---

使用示例

示例 1：岗位分析

const aiService = require('./services/ai_service');

const jobInfo = {
    companyName: '阿里巴巴',
    jobTitle: 'Node.js 高级工程师',
    salary: '30-50K',
    location: '杭州',
    description: '负责后端服务开发...',
    skills: 'Node.js, MySQL, Redis'
};

const resumeInfo = {
    skills: 'Node.js, JavaScript, MySQL',
    experience: '5年后端开发经验',
    education: '本科',
    expectedSalary: '35K'
};

const result = await aiService.analyzeJob(jobInfo, resumeInfo);
console.log(result.analysis);

示例 2：生成聊天内容

const result = await aiService.generateChatContent(
    jobInfo,
    resumeInfo,
    'greeting'  // greeting, interview, followup
);

console.log(result.content);

示例 3：简历分析

const resumeText = `
姓名：张三
技能：Node.js, React, MySQL
工作经验：3年全栈开发
...
`;

const result = await aiService.analyzeResume(resumeText);
console.log(result.analysis);
// {
//   skillTags: ['Node.js', 'React', 'MySQL'],
//   strengths: '...',
//   weaknesses: '...',
//   careerSuggestion: '...',
//   competitiveness: 75
// }

示例 4：自定义 AI 调用

const result = await aiService.callAPI(
    '请帮我分析这个岗位的发展前景...',
    {
        systemPrompt: '你是一个职业规划专家...',
        temperature: 0.7,
        maxTokens: 2000,
        user_id: 123,
        business_type: 'career_analysis'
    }
);

console.log(result.content);

---

错误处理

AI 服务内置了重试机制（最多 3 次）和错误处理：

try {
    const result = await aiService.analyzeJob(jobInfo, resumeInfo);
} catch (error) {
    console.error('AI 调用失败:', error.message);
    // 错误会自动记录到 ai_call_records 表
}

---

监控与统计

查看调用记录

登录后台管理系统：系统设置 → AI调用记录

统计信息

• 总调用次数
• Token 总使用量
• 总费用统计
• 平均响应时间
• 成功率

编程方式获取统计

const AiCallRecorder = require('./services/ai_call_recorder');

// 获取用户统计
const userStats = await AiCallRecorder.getUserTokenStats(userId, {
    startDate: new Date('2025-01-01'),
    endDate: new Date('2025-12-31')
});

console.log(userStats);
// {
//   total_calls: 100,
//   total_prompt_tokens: 5000,
//   total_completion_tokens: 3000,
//   total_tokens: 8000,
//   total_cost: 24.00,
//   avg_response_time: 1500
// }

---

注意事项

1. API Key 安全

• ❌ 不要将 API Key 硬编码在代码中
• ❌ 不要将 .env 文件提交到版本控制
• ✅ 使用环境变量管理 API Key
• ✅ 生产环境使用独立的 API Key

2. 成本控制

• 选择合适的模型（开发用 turbo，生产用 plus）
• 设置合理的 maxTokens 限制
• 监控 Token 使用量
• 定期查看费用统计

3. 性能优化

• 重试机制已内置（3 次）
• 超时设置为 30 秒
• Token 记录是异步的，不阻塞主流程

4. 数据隐私

• 请求和响应内容会完整记录到数据库
• 注意敏感信息的处理
• 定期清理历史记录

---

迁移指南

如果你的代码之前引用了 middleware/job/aiService.js，请修改为：

// ❌ 旧代码
const aiService = require('../middleware/job/aiService');

// ✅ 新代码
const aiService = require('../services/ai_service');

功能保持完全一致，只是路径发生了变化。

---

故障排查

问题 1：模型未加载

错误信息： Cannot read property 'findAll' of undefined

解决方法：

1. 确认已执行建表 SQL：_sql/create_ai_call_records_table.sql
2. 重启 Node.js 服务
3. 检查 api/model/ai_call_records.js 是否存在

问题 2：认证失败

错误信息： auth header format should be Bearer sk-...

解决方法：

1. 检查 .env 文件中的 AI_API_KEY
2. 确认 API Key 格式正确（以 sk- 开头）
3. 验证 API Key 有效性

问题 3：记录失败

警告信息： 记录AI调用失败（不影响主流程）

解决方法：

1. 检查数据库连接
2. 确认 ai_call_records 表存在
3. 查看详细错误日志

问题 4：费用计算不准确

解决方法：

1. 检查 calculateCost() 方法中的价格配置
2. 根据实际使用的模型调整价格
3. 定期对账单进行核对

---

相关文档

• AI 服务配置说明 - 详细的环境配置指南
• 功能实施总结 - 完整的功能实施文档
• API 文档 - 后台 API 接口说明

---

文档版本: 1.0 最后更新: 2025-12-27 维护者: 开发团队