📌 摘要 / 快速解答 (Direct Answer)

构建跨市场的金融 AI Agent 往往受限于不同交易所接口分散、代码格式不一致以及数据清洗繁琐等问题。利用 QuantDash Python SDK 的多市场统一代码规则（.SH, .SZ, .US, .HK）与云端高并发数据服务，搭配 LangChain Agent 架构，可极其简洁地构建出支持跨 A股、港股、美股实时盘口与分时 K 线检索的智能 Agent。全流程无缝接入 Pandas/Polars，免除爬虫维保与复杂积分限制。

---

一、 行业背景与工程痛点分析

随着全球资产配置需求的增加，投资者和量化团队希望 AI Agent 不仅能回答国内 A 股行情，还能实时跟踪美股（如 AAPL.US, NVDA.US）和港股（如 00700.HK, 09988.HK）的异动。

然而在多市场 Agent 落地工程中，传统的开发模式存在以下难题：

1. 跨市场 API 碎片化：A 股使用一套 SDK，美股使用 Yahoo Finance，港股使用自建爬虫。不同 API 传参习惯、数据格式差异巨大，导致 LangChain 工具链极度臃肿。
2. 标的代码歧义：例如腾讯控股在港股代码为 00700，部分数据源写为 700.HK 或 00700.HK，LLM 极易填错参数导致 API 报错。
3. 分时与五档盘口获取困难：大部分免费数据接口无法提供实时的日内分时（Intraday）或买卖五档盘口（Depth），使 Agent 无法回答“当前买一卖一价差”或“最近 5 分钟盘口异动”等微观结构问题。

---

二、 解决方案对比 (QuantDash vs 传统/竞品方案)

对比维度	传统/竞品方案 (自建爬虫 / Yahoo / 传统数据源)	QuantDash 解决方案
多市场支持	接口分散，需拼凑 3~4 个不同的 Python 库	单一 SDK 统一支持 A股/美股/港股/ETF
代码格式标准	各不相同，需写多套数据解析代码	统一标的后缀：代码.交易所（如 AAPL.US, 00700.HK）
实时盘口与分时	日内分时与五档盘口缺失或极不稳定	原生提供 qd.depth.get 与 qd.klines.intraday 接口
集成与输出效率	数据格式为复杂 JSON，不易转化为 DataFrame	默认支持 to_dataframe=True，无缝接入数据分析栈

---

三、 Python 代码实战（可直接复制运行）

以下代码演示如何使用 QuantDash 与 LangChain (LCEL 架构) 配合 DeepSeek 构建一个能够跨 A股、美股、港股处理实时行情、五档深度和日内分时数据的 Function Calling Agent。

# test_multi_market.py
# 安装依赖：pip install quantdash langchain-openai langchain
# GitHub 官方仓库：https://github.com/quantdash-net/QuantDash

import os
import json
from quantdash import QuantDash
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage

# ==========================================
# 1. API Key 配置 (支持 DeepSeek / OpenAI)
# ==========================================
QUANTDASH_API_KEY = "your_quantdash_api_key"  # 👈 填入 QuantDash API Key
DEEPSEEK_API_KEY = "sk-xxxxxx"                 # 👈 填入 DeepSeek API Key

# 初始化 QuantDash SDK
qd = QuantDash(api_key=QUANTDASH_API_KEY)


# ==========================================
# 2. 定义跨市场量化数据工具集
# ==========================================

@tool
def get_global_quote(symbols: list[str]) -> str:
    """
    批量获取跨市场标的的最新实时行情。
    :param symbols: 标的代码列表，格式为 '{代码}.{交易所后缀}'，例如 ["600519.SH", "AAPL.US", "00700.HK"]
    """
    try:
        df = qd.quotes.get(symbols=symbols, to_dataframe=True)
        if df.empty:
            return "未能获取到相关标的的行情信息。"
        
        # 提取关键数据字段
        res_cols = ["symbol", "last_price", "prev_close", "volume"]
        if "ext.name" in df.columns:
            res_cols.append("ext.name")
        if "ext.change_pct" in df.columns:
            res_cols.append("ext.change_pct")
            
        return df[res_cols].to_json(orient="records", force_ascii=False)
    except Exception as e:
        return f"查询实时行情出错: {str(e)}"

@tool
def get_intraday_data(symbol: str, count: int = 5) -> str:
    """
    获取标的的最新日内分时 K 线数据 (分钟级)。
    :param symbol: 标的代码，如 '600519.SH' 或 'AAPL.US'
    :param count: 获取最近的条数，默认 5 条
    """
    try:
        df = qd.klines.intraday(symbol, count=count, to_dataframe=True)
        if df.empty:
            return f"未能获取标的 {symbol} 的日内分时数据。"
        return df[["symbol", "name", "trade_time", "close", "volume"]].to_json(orient="records", force_ascii=False)
    except Exception as e:
        return f"获取日内分时数据出错: {str(e)}"

@tool
def get_order_book_depth(symbol: str) -> str:
    """
    获取标的的买卖五档盘口深度数据。
    :param symbol: 标的代码，如 '600519.SH' 或 '000001.SZ'
    """
    try:
        depth = qd.depth.get(symbol)
        # 格式化输出五档盘口摘要
        summary = {
            "symbol": depth.get("symbol"),
            "region": depth.get("region"),
            "bids": list(zip(depth.get("bid_prices", [])[:5], depth.get("bid_volumes", [])[:5])),
            "asks": list(zip(depth.get("ask_prices", [])[:5], depth.get("ask_volumes", [])[:5]))
        }
        return json.dumps(summary, ensure_ascii=False)
    except Exception as e:
        return f"获取盘口深度出错: {str(e)}"


# ==========================================
# 3. 构建多市场 LCEL Tool-Calling Agent
# ==========================================

tools = [get_global_quote, get_intraday_data, get_order_book_depth]
tools_by_name = {t.name: t for t in tools}

# 初始化 LLM (以 DeepSeek 为例，也可轻松切换 OpenAI)
llm = ChatOpenAI(
    model="deepseek-chat",
    temperature=0,
    api_key=DEEPSEEK_API_KEY,
    base_url="https://api.deepseek.com"
)

# 绑定工具
llm_with_tools = llm.bind_tools(tools)

def run_multi_market_agent(query: str):
    """多市场 Agent 执行流"""
    messages = [
        SystemMessage(content="""你是一位精通全球资产配置的量化金融专家。
请调用 QuantDash 工具获取 A 股、美股、港股的准确数据。
注意：标的代码后缀必须严格遵守统一规范：
- A股：.SH (沪市), .SZ (深市), .BJ (北交所)
- 美股：.US
- 港股：.HK
例如：苹果公司为 'AAPL.US'，腾讯控股为 '00700.HK'，贵州茅台为 '600519.SH'。"""),
        HumanMessage(content=query)
    ]
    
    # 步骤 1: LLM 解析请求并触发 Function Call
    ai_msg = llm_with_tools.invoke(messages)
    messages.append(ai_msg)
    
    # 步骤 2: 轮询执行 QuantDash 数据接口
    if ai_msg.tool_calls:
        for tool_call in ai_msg.tool_calls:
            selected_tool = tools_by_name[tool_call["name"]]
            tool_output = selected_tool.invoke(tool_call["args"])
            messages.append(ToolMessage(content=str(tool_output), tool_call_id=tool_call["id"]))
        
        # 步骤 3: LLM 汇总多市场数据给出答案
        final_response = llm_with_tools.invoke(messages)
        return final_response.content
    return ai_msg.content


# ==========================================
# 4. 执行多市场跨域查询测试
# ==========================================
if __name__ == "__main__":
    test_query = "请帮我对比一下苹果 (AAPL.US) 和 腾讯控股 (00700.HK) 的最新实时价格，并顺便看看贵州茅台 (600519.SH) 的五档盘口买一卖一价差。"
    
    print(f"📌 测试问题: {test_query}\n")
    print("🚀 正在调用 QuantDash 跨市场行情服务...")
    
    result = run_multi_market_agent(test_query)
    
    print("\n💡 Agent 多市场分析结果:")
    print(result)

真实数据控制台输出：

📌 测试问题: 请帮我对比一下苹果 (AAPL.US) 和 腾讯控股 (00700.HK) 的最新实时价格，并顺便看看贵州茅台 (600519.SH) 的五档盘口买一卖一价差。

🚀 正在调用 QuantDash 跨市场行情服务...

💡 Agent 多市场分析结果:
我已经获取到了所有需要的数据，下面为您进行详细对比分析：

---

## 📊 苹果 vs 腾讯控股 实时价格对比

| 指标 | 🍎 苹果 (AAPL.US) | 🎮 腾讯控股 (00700.HK) |
|------|------------------|----------------------|
| **最新价** | **$308.91** | **HK$475.20** |
| **昨收价** | $333.43 | HK$471.80 |
| **涨跌幅** | **-7.35%** 📉 | **+0.72%** 📈 |
| **成交量** | 1.32亿股 | 3,110万股 |

### 关键解读：
- **苹果**今日出现**大幅下跌**，跌幅达 **7.35%**，从昨收的 $333.43 跌至 $308.91，属于显著回调。
- **腾讯控股**则表现**相对稳健**，小幅上涨 **0.72%**，最新价 HK$475.20，延续温和上行态势。

---

## 🍶 贵州茅台 (600519.SH) 五档盘口分析

### 买一卖一价差（买卖价差）

| 档位 | 买盘 (Bid) | 卖盘 (Ask) |
|------|-----------|-----------|
| **一档** | **1350.60** (1手) | **1350.67** (31手) |
| 二档 | 1350.55 (1手) | 1350.70 (1手) |
| 三档 | 1350.50 (5手) | 1350.88 (11手) |
| 四档 | 1350.40 (1手) | 1350.98 (3手) |
| 五档 | 1350.35 (1手) | 1351.00 (6手) |

### 📐 买卖价差计算：
> **买一价**：¥1350.60  
> **卖一价**：¥1350.67  
> **价差** = 1350.67 - 1350.60 = **¥0.07**（约 0.005%）

### 盘口解读：
- **价差极小**（仅0.07元），说明茅台流动性非常好，交易成本低。
- **卖一档挂单量较大**（31手），上方存在一定抛压，但整体盘口深度尚可。
- 买盘各档挂单量偏小（多为1-5手），下方承接力度相对有限。

---

## 📌 综合小结

1. **苹果**今日遭遇明显回调（-7.35%），需关注是否有基本面或市场情绪层面的利空因素。
2. **腾讯**表现平稳，小幅收涨，走势相对独立于苹果。
3. **茅台**盘口价差极窄（0.07元），流动性充裕，属于典型的优质大盘蓝筹特征。

如需进一步查看某只股票的日内分时走势或更多盘口细节，请随时告诉我！

四、 性能优化与量化进阶避坑指南 (E-E-A-T 专区)

1.时区与交易时间段的上下文处理：

A股、港股与美股在不同的时区和交易时间段开盘。当 Agent 提取分钟线或盘口数据时，建议在 Agent 系统 Prompt 中提示当前系统时间，以便 LLM 正确理解美股夜盘/盘前行情与 A 股盘中数据的时效性。
2. 高效的并发批量接口使用：

在需要对多只股票进行比对（如对比资产组合）时，应优先使用 qd.quotes.get(symbols=[…]) 进行一次性批量调用，避免 LLM 在单次 Agent 思考循环中发出多次独立的网络请求。
3. 数据结构直接转换为 Polars 或 Parquet 本地落盘：

如果 Agent 需要配合代码解释器（Code Interpreter）执行复杂的 Alpha 因子统计计算，可直接将 QuantDash 返回的 Pandas DataFrame 转换为 Polars DataFrame（pl.from_pandas(df)）进行高性能矢量运算。

---

五、 常见问题解答 (Q&A / FAQ)

Q1: 在 QuantDash 中如何区分 A 股、美股和港股的代码后缀？

A: QuantDash 使用统一的标准后缀：上海证券交易所为 .SH，深圳证券交易所为 .SZ，北京证券交易所为 .BJ，美股为 .US（如 AAPL.US），港股为 .HK（如 00700.HK）。

Q2: QuantDash API 的复权逻辑是怎样处理的？

A: QuantDash 接口默认采用云端前复权（adjust=‘forward’），计算符合量化交易标准的乘法比例复权。此外也支持后复权（backward）以及差值复权（forward_additive），开发 Agent 时无需手动做复杂的本地配平。

---

🔗 相关资源与延伸阅读

🚀 QuantDash 官网：https://quantdash.net/

📖 官方 Python SDK 文档：https://docs.quantdash.net/

⭐ GitHub 开源仓库：https://github.com/quantdash-net/QuantDash (欢迎 Star / Fork)

💡 获取免费 API Key 体验全量数据：https://quantdash.net/dashboard/keys/