docs(nac-ai-valuation): 添加AI API集成指南
- ChatGPT-4.1注册和配置指南 - DeepSeek-V3注册和配置指南 - 豆包AI-Pro注册和配置指南 - 完整的集成代码示例 - 安全注意事项和故障排查 - 成本估算和优化建议
This commit is contained in:
NAC Development Team
parent
e998dc993e
commit
20e1ec6217
|
|
@ -0,0 +1,421 @@
|
||||||
|
# NAC AI资产估值系统 - AI API集成指南
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
本文档提供详细的AI API注册、配置和集成指南，帮助您将ChatGPT-4.1、DeepSeek-V3和豆包AI-Pro集成到NAC资产估值系统中。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 一、ChatGPT-4.1 API
|
||||||
|
|
||||||
|
### 1.1 注册步骤
|
||||||
|
|
||||||
|
1. **访问OpenAI官网**
|
||||||
|
- 网址：https://platform.openai.com/signup
|
||||||
|
- 使用邮箱或Google账号注册
|
||||||
|
|
||||||
|
2. **验证邮箱**
|
||||||
|
- 检查邮箱收到的验证邮件
|
||||||
|
- 点击链接完成验证
|
||||||
|
|
||||||
|
3. **完善账户信息**
|
||||||
|
- 填写个人/企业信息
|
||||||
|
- 选择使用场景（选择"Business/Enterprise"）
|
||||||
|
|
||||||
|
4. **绑定支付方式**
|
||||||
|
- 进入Billing页面：https://platform.openai.com/account/billing/overview
|
||||||
|
- 添加信用卡（支持Visa、Mastercard、American Express）
|
||||||
|
- 设置每月预算上限（建议至少$50）
|
||||||
|
|
||||||
|
### 1.2 获取API密钥
|
||||||
|
|
||||||
|
1. **创建API Key**
|
||||||
|
- 进入API Keys页面：https://platform.openai.com/api-keys
|
||||||
|
- 点击"Create new secret key"
|
||||||
|
- 命名为"NAC-Valuation-System"
|
||||||
|
- **重要**：立即复制并保存密钥，页面关闭后无法再次查看
|
||||||
|
|
||||||
|
2. **密钥格式**
|
||||||
|
```
|
||||||
|
sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.3 计费说明
|
||||||
|
|
||||||
|
- **模型**：`gpt-4-turbo` 或 `gpt-4o`
|
||||||
|
- **价格**（截至2026年2月）：
|
||||||
|
- 输入：$10/1M tokens
|
||||||
|
- 输出：$30/1M tokens
|
||||||
|
- **估算**：每次估值约消耗2000 tokens，成本约$0.08
|
||||||
|
|
||||||
|
### 1.4 配置示例
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 环境变量
|
||||||
|
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
export OPENAI_API_BASE="https://api.openai.com/v1"
|
||||||
|
export OPENAI_MODEL="gpt-4-turbo"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 二、DeepSeek-V3 API
|
||||||
|
|
||||||
|
### 2.1 注册步骤
|
||||||
|
|
||||||
|
1. **访问DeepSeek官网**
|
||||||
|
- 网址：https://platform.deepseek.com/signup
|
||||||
|
- 使用手机号或邮箱注册（支持中国大陆手机号）
|
||||||
|
|
||||||
|
2. **实名认证**
|
||||||
|
- 上传身份证正反面照片
|
||||||
|
- 填写真实姓名和身份证号
|
||||||
|
- 等待审核（通常1-2小时）
|
||||||
|
|
||||||
|
3. **充值**
|
||||||
|
- 进入充值页面：https://platform.deepseek.com/billing
|
||||||
|
- 支持支付宝、微信支付、银行卡
|
||||||
|
- 最低充值金额：¥100
|
||||||
|
|
||||||
|
### 2.2 获取API密钥
|
||||||
|
|
||||||
|
1. **创建API Key**
|
||||||
|
- 进入API管理页面：https://platform.deepseek.com/api_keys
|
||||||
|
- 点击"创建新密钥"
|
||||||
|
- 命名为"NAC资产估值系统"
|
||||||
|
- 设置权限：勾选"模型调用"
|
||||||
|
- 点击"创建"并保存密钥
|
||||||
|
|
||||||
|
2. **密钥格式**
|
||||||
|
```
|
||||||
|
sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.3 计费说明
|
||||||
|
|
||||||
|
- **模型**：`deepseek-chat`（V3版本）
|
||||||
|
- **价格**：
|
||||||
|
- 输入：¥1/1M tokens
|
||||||
|
- 输出：¥2/1M tokens
|
||||||
|
- **估算**：每次估值约消耗2000 tokens，成本约¥0.006（非常便宜）
|
||||||
|
|
||||||
|
### 2.4 配置示例
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 环境变量
|
||||||
|
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
export DEEPSEEK_API_BASE="https://api.deepseek.com/v1"
|
||||||
|
export DEEPSEEK_MODEL="deepseek-chat"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、豆包AI-Pro API
|
||||||
|
|
||||||
|
### 3.1 注册步骤
|
||||||
|
|
||||||
|
1. **访问火山引擎官网**
|
||||||
|
- 网址：https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint
|
||||||
|
- 使用手机号注册（必须是中国大陆手机号）
|
||||||
|
|
||||||
|
2. **企业认证**
|
||||||
|
- 进入账户中心：https://console.volcengine.com/user/basics
|
||||||
|
- 选择"企业认证"或"个人认证"
|
||||||
|
- 上传营业执照（企业）或身份证（个人）
|
||||||
|
- 等待审核（1-3个工作日）
|
||||||
|
|
||||||
|
3. **开通豆包服务**
|
||||||
|
- 进入豆包大模型页面：https://console.volcengine.com/ark
|
||||||
|
- 点击"立即开通"
|
||||||
|
- 选择"按量付费"模式
|
||||||
|
|
||||||
|
4. **充值**
|
||||||
|
- 进入费用中心：https://console.volcengine.com/finance/account
|
||||||
|
- 充值金额：最低¥100
|
||||||
|
- 支持支付宝、银行转账
|
||||||
|
|
||||||
|
### 3.2 获取API密钥
|
||||||
|
|
||||||
|
1. **创建API Key**
|
||||||
|
- 进入API密钥管理：https://console.volcengine.com/iam/keymanage
|
||||||
|
- 点击"新建密钥"
|
||||||
|
- 记录Access Key ID和Secret Access Key
|
||||||
|
|
||||||
|
2. **创建推理接入点**
|
||||||
|
- 进入模型推理：https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint
|
||||||
|
- 选择模型：`doubao-pro-32k`
|
||||||
|
- 创建接入点，记录Endpoint ID
|
||||||
|
|
||||||
|
3. **密钥格式**
|
||||||
|
```
|
||||||
|
Access Key ID: AKLTxxxxxxxxxxxxxxxxxxxxxxxx
|
||||||
|
Secret Access Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||||
|
Endpoint ID: ep-xxxxxxxxxxxxxxxx
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 计费说明
|
||||||
|
|
||||||
|
- **模型**：`doubao-pro-32k`
|
||||||
|
- **价格**：
|
||||||
|
- 输入：¥0.8/1M tokens
|
||||||
|
- 输出：¥2/1M tokens
|
||||||
|
- **估算**：每次估值约消耗2000 tokens，成本约¥0.0056
|
||||||
|
|
||||||
|
### 3.4 配置示例
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 环境变量
|
||||||
|
export DOUBAO_ACCESS_KEY="AKLTxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
export DOUBAO_SECRET_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
export DOUBAO_ENDPOINT_ID="ep-xxxxxxxxxxxxxxxx"
|
||||||
|
export DOUBAO_REGION="cn-beijing"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、集成到NAC系统
|
||||||
|
|
||||||
|
### 4.1 配置文件
|
||||||
|
|
||||||
|
创建配置文件 `/home/ubuntu/NAC_Clean_Dev/nac-ai-valuation/config.toml`：
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[ai_models]
|
||||||
|
# ChatGPT配置
|
||||||
|
[ai_models.chatgpt]
|
||||||
|
api_key = "sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
api_base = "https://api.openai.com/v1"
|
||||||
|
model = "gpt-4-turbo"
|
||||||
|
timeout = 30 # 秒
|
||||||
|
|
||||||
|
# DeepSeek配置
|
||||||
|
[ai_models.deepseek]
|
||||||
|
api_key = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
api_base = "https://api.deepseek.com/v1"
|
||||||
|
model = "deepseek-chat"
|
||||||
|
timeout = 30
|
||||||
|
|
||||||
|
# 豆包AI配置
|
||||||
|
[ai_models.doubao]
|
||||||
|
access_key = "AKLTxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
secret_key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
endpoint_id = "ep-xxxxxxxxxxxxxxxx"
|
||||||
|
region = "cn-beijing"
|
||||||
|
timeout = 30
|
||||||
|
|
||||||
|
[valuation]
|
||||||
|
# XTZH当前价格（USD）
|
||||||
|
xtzh_price_usd = 100.0
|
||||||
|
|
||||||
|
# 仲裁配置
|
||||||
|
[valuation.arbitration]
|
||||||
|
weighted_voting_weight = 0.70
|
||||||
|
bayesian_fusion_weight = 0.30
|
||||||
|
cv_threshold = 0.15
|
||||||
|
confidence_threshold = 0.70
|
||||||
|
high_value_threshold = 10000000 # 1000万XTZH
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 环境变量方式
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 创建 .env 文件
|
||||||
|
cat > /home/ubuntu/NAC_Clean_Dev/nac-ai-valuation/.env << 'EOF'
|
||||||
|
# ChatGPT
|
||||||
|
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||||
|
OPENAI_API_BASE=https://api.openai.com/v1
|
||||||
|
OPENAI_MODEL=gpt-4-turbo
|
||||||
|
|
||||||
|
# DeepSeek
|
||||||
|
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||||
|
DEEPSEEK_API_BASE=https://api.deepseek.com/v1
|
||||||
|
DEEPSEEK_MODEL=deepseek-chat
|
||||||
|
|
||||||
|
# 豆包AI
|
||||||
|
DOUBAO_ACCESS_KEY=AKLTxxxxxxxxxxxxxxxxxxxxxxxx
|
||||||
|
DOUBAO_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||||
|
DOUBAO_ENDPOINT_ID=ep-xxxxxxxxxxxxxxxx
|
||||||
|
DOUBAO_REGION=cn-beijing
|
||||||
|
|
||||||
|
# XTZH价格
|
||||||
|
XTZH_PRICE_USD=100.0
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 代码示例
|
||||||
|
|
||||||
|
```rust
|
||||||
|
use nac_ai_valuation::{ValuationEngine, ValuationEngineConfig, Asset, AssetType, Jurisdiction, InternationalAgreement};
|
||||||
|
use rust_decimal::Decimal;
|
||||||
|
use std::env;
|
||||||
|
|
||||||
|
#[tokio::main]
|
||||||
|
async fn main() -> anyhow::Result<()> {
|
||||||
|
// 从环境变量读取API密钥
|
||||||
|
let chatgpt_key = env::var("OPENAI_API_KEY")?;
|
||||||
|
let deepseek_key = env::var("DEEPSEEK_API_KEY")?;
|
||||||
|
let doubao_key = format!(
|
||||||
|
"{}:{}:{}",
|
||||||
|
env::var("DOUBAO_ACCESS_KEY")?,
|
||||||
|
env::var("DOUBAO_SECRET_KEY")?,
|
||||||
|
env::var("DOUBAO_ENDPOINT_ID")?
|
||||||
|
);
|
||||||
|
|
||||||
|
// 创建估值引擎
|
||||||
|
let engine = ValuationEngine::new(
|
||||||
|
chatgpt_key,
|
||||||
|
deepseek_key,
|
||||||
|
doubao_key,
|
||||||
|
ValuationEngineConfig::default(),
|
||||||
|
)?;
|
||||||
|
|
||||||
|
// 创建资产
|
||||||
|
let asset = Asset::new(
|
||||||
|
"asset_001".to_string(),
|
||||||
|
AssetType::RealEstate,
|
||||||
|
"GNACS-RE-001".to_string(),
|
||||||
|
"Manhattan Office Building".to_string(),
|
||||||
|
Decimal::new(50_000_000, 0), // $50M
|
||||||
|
"USD".to_string(),
|
||||||
|
);
|
||||||
|
|
||||||
|
// 执行估值
|
||||||
|
let result = engine.appraise(
|
||||||
|
&asset,
|
||||||
|
Jurisdiction::US,
|
||||||
|
InternationalAgreement::WTO,
|
||||||
|
).await?;
|
||||||
|
|
||||||
|
// 输出结果
|
||||||
|
println!("估值结果: {} XTZH", result.valuation_xtzh);
|
||||||
|
println!("置信度: {:.1}%", result.confidence * 100.0);
|
||||||
|
println!("需要人工审核: {}", result.requires_human_review);
|
||||||
|
|
||||||
|
// 生成报告
|
||||||
|
let report = result.generate_report();
|
||||||
|
println!("\n{}", report);
|
||||||
|
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、安全注意事项
|
||||||
|
|
||||||
|
### 5.1 密钥管理
|
||||||
|
|
||||||
|
1. **永远不要**将API密钥提交到Git仓库
|
||||||
|
2. 使用 `.gitignore` 忽略配置文件：
|
||||||
|
```
|
||||||
|
.env
|
||||||
|
config.toml
|
||||||
|
*.key
|
||||||
|
```
|
||||||
|
|
||||||
|
3. 使用环境变量或密钥管理服务（如HashiCorp Vault）
|
||||||
|
|
||||||
|
### 5.2 访问控制
|
||||||
|
|
||||||
|
1. 定期轮换API密钥（建议每3个月）
|
||||||
|
2. 为不同环境使用不同的密钥（开发、测试、生产）
|
||||||
|
3. 设置API调用频率限制
|
||||||
|
|
||||||
|
### 5.3 成本控制
|
||||||
|
|
||||||
|
1. 设置每月预算上限
|
||||||
|
2. 监控API调用量和成本
|
||||||
|
3. 实现缓存机制，避免重复调用
|
||||||
|
4. 对于低价值资产，可以只调用DeepSeek或豆包AI（成本更低）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 六、故障排查
|
||||||
|
|
||||||
|
### 6.1 常见错误
|
||||||
|
|
||||||
|
#### 错误1：API密钥无效
|
||||||
|
```
|
||||||
|
Error: Invalid API key
|
||||||
|
```
|
||||||
|
**解决方案**：
|
||||||
|
- 检查密钥是否正确复制（注意空格）
|
||||||
|
- 确认密钥未过期
|
||||||
|
- 重新生成密钥
|
||||||
|
|
||||||
|
#### 错误2：余额不足
|
||||||
|
```
|
||||||
|
Error: Insufficient balance
|
||||||
|
```
|
||||||
|
**解决方案**：
|
||||||
|
- 充值账户
|
||||||
|
- 检查计费设置
|
||||||
|
|
||||||
|
#### 错误3：请求超时
|
||||||
|
```
|
||||||
|
Error: Request timeout
|
||||||
|
```
|
||||||
|
**解决方案**：
|
||||||
|
- 增加timeout设置
|
||||||
|
- 检查网络连接
|
||||||
|
- 使用代理（如果在中国大陆访问OpenAI）
|
||||||
|
|
||||||
|
#### 错误4：速率限制
|
||||||
|
```
|
||||||
|
Error: Rate limit exceeded
|
||||||
|
```
|
||||||
|
**解决方案**：
|
||||||
|
- 降低请求频率
|
||||||
|
- 升级API套餐
|
||||||
|
- 实现请求队列和重试机制
|
||||||
|
|
||||||
|
### 6.2 测试连接
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 测试ChatGPT
|
||||||
|
curl https://api.openai.com/v1/chat/completions \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-H "Authorization: Bearer $OPENAI_API_KEY" \
|
||||||
|
-d '{
|
||||||
|
"model": "gpt-4-turbo",
|
||||||
|
"messages": [{"role": "user", "content": "Hello"}]
|
||||||
|
}'
|
||||||
|
|
||||||
|
# 测试DeepSeek
|
||||||
|
curl https://api.deepseek.com/v1/chat/completions \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
|
||||||
|
-d '{
|
||||||
|
"model": "deepseek-chat",
|
||||||
|
"messages": [{"role": "user", "content": "你好"}]
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 七、联系支持
|
||||||
|
|
||||||
|
- **OpenAI支持**：https://help.openai.com
|
||||||
|
- **DeepSeek支持**：https://platform.deepseek.com/docs
|
||||||
|
- **豆包AI支持**：https://www.volcengine.com/docs/82379
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 八、附录：完整示例项目
|
||||||
|
|
||||||
|
完整的集成示例代码位于：
|
||||||
|
```
|
||||||
|
/home/ubuntu/NAC_Clean_Dev/nac-ai-valuation/examples/full_integration.rs
|
||||||
|
```
|
||||||
|
|
||||||
|
运行示例：
|
||||||
|
```bash
|
||||||
|
cd /home/ubuntu/NAC_Clean_Dev/nac-ai-valuation
|
||||||
|
cargo run --example full_integration
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**文档版本**：v1.0
|
||||||
|
**最后更新**：2026-02-18
|
||||||
|
**维护者**：NAC开发团队
|
||||||
Loading…
Reference in New Issue