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