# 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开发团队