ljwx-stock/AI_ASSISTANT_USAGE_GUIDE.md

AI 助手使用指南

📌 快速入门

通过 AI 助手，你可以用自然语言直接提问，系统会自动执行完整的 Claude → DeepSeek → Yahoo Finance → Claude 分析流程。

最简洁的方式

# 直接提问，系统自动分析
curl "http://localhost:8001/api/ai-assistant/quick-ask?question=AAPL%20%E7%8E%B0%E5%9C%A8%E6%98%AF%E4%B8%8D%E6%98%AF%E5%A5%BD%E7%9A%84%E4%B9%B0%E5%85%A5%E7%82%B9"

# 或使用 POST 带更多参数
curl -X POST http://localhost:8001/api/ai-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "AAPL 和 MSFT 哪个更值得买？",
    "symbols": ["AAPL", "MSFT"]
  }'

🎯 常见问题和使用场景

1️⃣ 单个股票分析

问题示例：

"AAPL 现在是不是好的买入点？"
"分析一下 Tesla 最近的表现"
"MSFT 的技术面怎么样？"

API 调用：

curl -X POST http://localhost:8001/api/ai-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "AAPL 现在是不是好的买入点？",
    "symbols": ["AAPL"]
  }'

返回结果包含：

• 当前价格和基本信息
• DeepSeek 技术指标分析
• Claude 投资建议
• 三档策略建议
• 风险评估

---

2️⃣ 股票对比

问题示例：

"AAPL 和 MSFT 哪个更值得买？"
"对比 Apple、Google、Microsoft"
"在 NVDA 和 TSLA 之间选择，哪个更好？"

API 调用：

# 方式 1：直接提问，系统自动提取
curl -X POST http://localhost:8001/api/ai-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "AAPL 和 MSFT 哪个更值得买？"
  }'

# 方式 2：使用对比 API
curl -X POST "http://localhost:8001/api/ai-assistant/compare?symbols=AAPL&symbols=MSFT"

---

3️⃣ 寻找投资机会

问题示例：

"找出最近涨幅最大的科技股"
"在科技行业中找出最有投资价值的股票"
"有什么低估的股票吗？"

API 调用：

# 方式 1：直接提问
curl "http://localhost:8001/api/ai-assistant/quick-ask?question=找出最近涨幅最大的科技股"

# 方式 2：使用寻找最佳 API
curl -X POST "http://localhost:8001/api/ai-assistant/find-best?criteria=best_investment"

---

4️⃣ 市场整体分析

问题示例：

"当前市场形势如何？"
"最近哪些板块表现最好？"
"市场现在是牛市还是熊市？"

API 调用：

curl -X GET http://localhost:8001/api/ai-assistant/market-pulse

---

5️⃣ 投资组合分析

问题示例：

"我有 AAPL、MSFT、NVDA，这个组合平衡吗？"
"建议我调整投资组合吗？"
"这些股票的风险怎么样？"

API 调用：

curl -X POST "http://localhost:8001/api/ai-assistant/portfolio-balance?symbols=AAPL&symbols=MSFT&symbols=NVDA"

---

6️⃣ 情景分析 ("如果...会怎样？")

问题示例：

"如果 Fed 加息，AAPL 会怎样？"
"如果芯片供应链改善，NVDA 会涨多少？"
"万一市场下跌 10%，我的投资组合怎样？"

API 调用：

curl -X POST "http://localhost:8001/api/ai-assistant/what-if?scenario=股票上升10%&symbol=AAPL"

---

7️⃣ 交易行动建议

问题示例：

"请分析 TSLA，给出明确的交易建议（买入、卖出、持有）"
"MSFT 现在应该如何操作？"
"我应该现在加仓吗？"

API 调用：

curl -X GET "http://localhost:8001/api/ai-assistant/suggest-action/AAPL"

---

8️⃣ 风险评估

问题示例：

"AAPL 的风险有多大？"
"这些股票中哪个风险最高？"
"我的投资组合有什么潜在风险？"

API 调用：

curl -X POST "http://localhost:8001/api/ai-assistant/risk-assessment?symbols=AAPL&symbols=MSFT"

---

9️⃣ 趋势分析

问题示例：

"分析 AAPL 在最近 3 个月的趋势"
"这个股票是上升趋势还是下降趋势？"
"最近半年哪个股票表现最好？"

API 调用：

curl -X POST "http://localhost:8001/api/ai-assistant/analyze-trend?symbols=AAPL&symbols=MSFT&period=3mo"

---

🔄 工作流程

当你提交一个自然语言问题时，系统会自动执行以下步骤：

[用户问题]
    ↓
[Step 1] Claude 解析问题
    ├─ 提取股票符号
    ├─ 识别分析类型
    └─ 确定所需数据
    ↓
[Step 2] 获取数据 (Yahoo Finance)
    ├─ 当前价格
    ├─ 历史数据
    ├─ 计算技术指标 (MA, RSI, MACD)
    └─ 获取市场快照
    ↓
[Step 3] DeepSeek 量化分析
    ├─ 分析技术指标
    ├─ 生成交易信号
    ├─ 评估置信度
    └─ 返回 JSON 结果
    ↓
[Step 4] Claude 生成投资建议
    ├─ 理解 DeepSeek 信号
    ├─ 融合市场背景
    ├─ 生成三档策略
    ├─ 添加风险提示
    └─ 生成自然语言总结
    ↓
[返回完整分析结果]

总耗时：首次 7-15 秒，缓存命中 <50ms

---

📋 API 端点完整列表

直接提问

端点	方法	说明	示例
/api/ai-assistant/ask	POST	提问（带符号列表）	{"question": "...", "symbols": [...]}
/api/ai-assistant/quick-ask	POST	快速提问（最简洁）	?question=...

股票分析

端点	方法	说明
/api/ai-assistant/compare	POST	对比多个股票
/api/ai-assistant/find-best	POST	寻找最佳股票
/api/ai-assistant/quick-signal/{symbol}	GET	快速获取信号
/api/ai-assistant/suggest-action/{symbol}	GET	交易建议

高级分析

端点	方法	说明
/api/ai-assistant/analyze-trend	POST	趋势分析
/api/ai-assistant/find-opportunity	POST	寻找投资机会
/api/ai-assistant/market-pulse	GET	市场脉搏
/api/ai-assistant/what-if	POST	情景分析
/api/ai-assistant/portfolio-balance	POST	投资组合平衡
/api/ai-assistant/risk-assessment	POST	风险评估

帮助

端点	方法	说明
/api/ai-assistant/examples	GET	获取示例

---

💡 使用技巧

技巧 1：提供明确的符号

如果你不确定系统是否理解符号，可以显式提供：

curl -X POST http://localhost:8001/api/ai-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "对比这两只股票",
    "symbols": ["AAPL", "MSFT"]
  }'

技巧 2：使用特定的 API 端点更快

如果你知道需要什么类型的分析，使用专门的端点会更快：

# 对比时使用专门的 compare 端点
curl -X POST "http://localhost:8001/api/ai-assistant/compare?symbols=AAPL&symbols=MSFT"

# 而不是
curl -X POST http://localhost:8001/api/ai-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "对比 AAPL 和 MSFT"}'

技巧 3：链式问题

你可以根据第一个问题的结果继续提问：

# 第一个问题：找出最佳股票
curl "http://localhost:8001/api/ai-assistant/quick-ask?question=找出最具投资价值的科技股"

# 根据结果再问
curl "http://localhost:8001/api/ai-assistant/quick-ask?question=如果选中的股票上升20%，会怎样？"

---

🔍 理解返回结果

返回结构

{
  "status": "success",
  "timestamp": "2025-11-12T10:30:00",
  "user_request": "用户的问题",
  "analysis_type": "recommendation|technical|comparative|...",
  "symbols_analyzed": ["AAPL", "MSFT"],

  "stocks_data": {
    "AAPL": {
      "quote": {
        "symbol": "AAPL",
        "price": 151.00,
        "name": "Apple Inc."
      },
      "indicators": {
        "ma5": 150.50,
        "ma20": 149.20,
        "rsi": 65.5,
        "macd": {...}
      }
    }
  },

  "deepseek_signals": {
    "AAPL": {
      "signal": "BUY",
      "confidence": 0.75,
      "reason": "MA5 突破 MA20，RSI 处于上升态势",
      "risk_level": "MEDIUM"
    }
  },

  "recommendations": {
    "AAPL": {
      "recommendation": "建议买入",
      "summary": "技术面看涨，量化信号强劲",
      "strategies": {
        "aggressive": {...},
        "balanced": {...},
        "conservative": {...}
      },
      "entry_price": 150.25,
      "stop_loss": 145.00,
      "take_profit": 160.00,
      "risks": [...],
      "confidence": 0.72
    }
  },

  "summary": "自然语言总结"
}

关键字段说明

• signal：DeepSeek 的交易信号 (BUY/SELL/HOLD)
• confidence：DeepSeek 对该信号的置信度 (0.0-1.0)
• recommendation：Claude 的投资建议
• strategies：三档投资策略 (激进/平衡/保守)
• risk_level：风险等级 (LOW/MEDIUM/HIGH)
• entry_price：建议入场价
• stop_loss：止损价
• take_profit：止盈价

---

🛠️ 故障排查

Q: 收到"无法识别股票符号"错误？

A: 确保问题中包含有效的股票代码（如 AAPL, MSFT），或使用 symbols 参数明确指定。

Q: API 响应很慢？

A:

• 首次分析会较慢（7-15 秒）
• 缓存命中会很快（<50ms）
• 如果 Ollama 未就绪，会自动返回默认信号

Q: 分析结果质量不好？

A:

• 确保 Ollama 容器已启动并加载模型
• 检查 OPENROUTER_API_KEY 是否正确配置
• 参考日志：docker-compose logs backend

---

📚 示例代码

Python

import httpx
import asyncio

async def ask_ai(question: str, symbols: list = None):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            'http://localhost:8001/api/ai-assistant/ask',
            json={
                'question': question,
                'symbols': symbols
            }
        )
        return response.json()

# 使用
result = asyncio.run(ask_ai('AAPL 现在是不是好的买入点？'))
print(result)

JavaScript

async function askAI(question, symbols = null) {
  const response = await fetch('/api/ai-assistant/ask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ question, symbols })
  })
  return await response.json()
}

// 使用
const result = await askAI('AAPL 现在是不是好的买入点？')
console.log(result)

cURL

# 最简单的方式
curl "http://localhost:8001/api/ai-assistant/quick-ask?question=AAPL%20怎么样"

# 完整方式
curl -X POST http://localhost:8001/api/ai-assistant/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "AAPL 和 MSFT 哪个更值得买？",
    "symbols": ["AAPL", "MSFT"]
  }'

---

🎓 最佳实践

1. 提供明确的符号

   • 系统会尽量从问题中提取，但明确提供更稳妥

2. 使用专门的 API 端点

   • 对比时用 /compare
   • 分析趋势时用 /analyze-trend
   • 这样会更快更准确

3. 理解三档策略

   • 激进：追求高收益，接受高风险
   • 平衡：寻求中等风险收益
   • 保守：优先保本，接受低收益

4. 关注风险提示

   • 总是查看 risks 字段
   • 了解每个建议的潜在风险

5. 缓存利用

   • 同一查询第二次会很快
   • 定期刷新以获取最新数据

---

Happy Trading! 🚀

通过 AI 助手，投资分析变得简单、快速、准确！