easy_tdx 详细部署教程：免费开源 A 股量化 SDK

easy_tdx 是一个完全免费、无需注册、无需 API Key 的 Python 量化 SDK，通过直连通达信协议，可获取 A 股、港股、美股、期货的毫秒级行情数据，并内置了 34 个技术指标、缠论分析、回测引擎与 Web 可视化界面。本教程将带你从零开始部署并掌握这个强大的工具。

---

1. 系统要求与安装

1.1 环境要求

• Python 版本：3.8 至 3.11（3.12 版本可能存在兼容性问题，建议使用 3.11）。
• 操作系统：Windows、Linux、macOS。
• 网络：能够访问互联网以连接通达信行情服务器。

1.2 安装 easy_tdx

最推荐的安装方式是通过 pip 直接安装核心库：

pip install easy-tdx

按需安装可选依赖：

安装命令	说明
pip install easy-tdx[web]	安装 Web API 服务（FastAPI + Uvicorn）及 Web UI 依赖
pip install easy-tdx[science]	安装科学计算依赖（如 scipy），用于高级因子优化
pip install easy-tdx[warehouse]	安装本地 K 线仓库（DuckDB）支持
pip install -e ".[dev]"	安装开发模式依赖（pytest, mypy, ruff 等）

安装完成后，在终端中运行以下命令验证安装：

easy-tdx --help

如果看到命令帮助信息，则说明安装成功。

---

2. 基本配置与连接

2.1 配置层级

easy_tdx 的配置按以下优先级生效（高到低）：

1. 环境变量（最高）：如 EASY_TDX_HOST（指定服务器 IP）、EASY_TDX_PORT（指定端口）、EASY_TDX_TIMEOUT（超时时间）。
2. 本地配置文件：~/.easy_tdx/config.json，系统会自动保存延迟最低的服务器地址。
3. 内置默认值（最低）。

2.2 连接测试

使用 ping 命令测试通达信服务器的延迟，系统会自动选择最优服务器并保存到本地配置：

easy-tdx ping

2.3 选择客户端类

在 Python 代码中，可根据需求选择不同的客户端：

客户端类	协议	市场覆盖	适用场景
TdxClient / AsyncTdxClient	标准 TCP	A 股 L1 行情、K 线	通用脚本、Web 服务
MacClient / AsyncMacClient	MAC（二进制）	A 股 L2 风格、自动复权	高频更新
ExTdxClient / MacExClient	扩展 TCP / MAC	期货、期权、港股、美股	衍生品和全球市场
UnifiedTdxClient	多协议	A 股 + 扩展市场	统一接口访问所有品种

推荐使用 MacClient，它支持更快的 MAC 协议和自动复权。

---

3. 基础功能快速上手

3.1 命令行（CLI）速览

easy_tdx 的所有 CLI 命令默认输出 JSON，非常适配 AI Agent 处理。加上 --table 可切换为表格形式。

获取 K 线数据：

# 获取贵州茅台（SH 600519）最近 30 条日 K 线，前复权，表格形式显示
easy-tdx kline SH 600519 --count 30 --adjust QFQ --table

# 获取 5 分钟线
easy-tdx kline SH 600519 --period 5MIN --count 50 --table

获取实时报价：

# 获取单只或多只股票实时报价
easy-tdx quote "SZ 000001,SH 600519" --table

# 获取全 A 股涨幅排名前 20
easy-tdx quote-list A --count 20 --table

计算技术指标：

# 计算 MACD、KDJ、RSI 指标
easy-tdx indicator MACD,KDJ,RSI -m SH -c 600519 --count 30 --table

# 自定义 MACD 参数
easy-tdx indicator MACD -m SH -c 600519 --params SHORT=10,LONG=22 --table

支持 34 个技术指标，包括 MACD、KDJ、RSI、BOLL、DMI、ATR 及“捉妖大师（ZHUOYAO）”和“30日乖离率信号（BIAS_SIGNAL）”等特色指标。

缠论分析：
一键完成从 K 线合并到买卖点、背驰的全部分析：

easy-tdx chanlun SZ 000001 --table

3.2 Python API 示例

在 Python 脚本中使用 easy_tdx 同样简单：

from easy_tdx import MacClient, Market, Adjust

# 自动连接最优服务器
with MacClient.from_best_host() as client:
    # 获取日 K 线，前复权
    df = client.get_stock_kline(
        Market.SH, "600519",
        count=30,
        adjust=Adjust.QFQ
    )
    print(df.tail())

    # 获取 K 线 + 技术指标（一步到位）
    df_indicators = client.get_stock_kline_with_indicators(
        Market.SH, "600519",
        indicators=["MACD", "KDJ", "RSI", "BOLL"],
        count=30
    )
    print(df_indicators.columns)

---

4. 高级功能：部署 Web 可视化终端（Web UI）

easy-tdx serve 命令可以一键启动一个包含行情终端和回测工作台的 Web 可视化界面。

4.1 安装 Web 依赖并启动

# 确保已安装 Web 依赖
pip install easy-tdx[web]

# 启动 Web 服务（默认端口 8000），浏览器会自动打开
easy-tdx serve

# 自定义端口
easy-tdx serve --port 8080

4.2 界面功能

Web UI 包含两大核心模块：

• 行情终端：市场看板、行业/概念总览（含热力图）、自选行情、龙头池、期货持仓排名。
• 回测工作台：单标的回测、组合回测、参数网格寻优、多策略结果对比、策略库（SQLite 持久化）。回测结果包含 25 项绩效指标、S/A/B/C/D 五档评级和 Walk-Forward 样本外验证。

注意：Web UI 的后端是 FastAPI 服务，前端是 Vue 3 单页应用，由后端同源托管。无需单独运行前端开发服务器。

---

5. 回测引擎快速入门

easy_tdx 内置了向量化回测引擎，支持 50+ 内置策略。

5.1 使用内置策略回测

# 对中际旭创（SZ 300308）使用 expma_cross 策略回测，使用 2000 根 K 线，初始资金 100 万
easy-tdx backtest SZ 300308 \
  --strategy-file strategies/expma_cross.py \
  --count 2000 --cash 1000000 --adjust QFQ --table

5.2 批量运行所有策略并排名

# 运行 strategies/ 目录下所有策略，按总收益率排名
easy-tdx run-all SZ 300308 --count 2000 --cash 1000000 --adjust QFQ

# 添加 --show 参数，用 matplotlib 弹出资金曲线对比图（需先安装 matplotlib）
easy-tdx run-all SZ 300308 --count 2000 --cash 1000000 --adjust QFQ --show

run-all 支持多因子组合回测（--combo 2 --combo-mode MAJORITY）和自定义策略目录。

5.3 编写自定义策略

只需继承 Strategy 基类，在 init() 中注册指标，在 next() 中实现交易逻辑：

from easy_tdx.backtest import Strategy
from easy_tdx import MyTT

class MyMACrossStrategy(Strategy):
    def init(self):
        # 计算 5 日和 20 日均线
        self.ma5 = self.I(MyTT.MA, self.data.close, 5)
        self.ma20 = self.I(MyTT.MA, self.data.close, 20)

    def next(self):
        # 金叉买入，死叉卖出
        if self.ma5[self._bar_index] > self.ma20[self._bar_index] and self.position["size"] == 0:
            self.buy(size=0)  # 全仓买入
        elif self.ma5[self._bar_index] < self.ma20[self._bar_index] and self.position["size"] > 0:
            self.sell(size=0) # 清仓卖出

---

6. 常见问题与故障排查

• 数据获取失败：检查网络连接，确保能访问通达信行情服务器。可以尝试更新 akshare 库（pip install --upgrade akshare），因为部分功能依赖它作为备用数据源。
• Web UI 无法启动：确认已安装 easy-tdx[web] 依赖。检查端口 8000 是否被占用，或通过 --port 指定其他端口。
• 价格精度异常（如 ETF 价格放大 10 倍）：v1.15.4 版本已修复此问题。请升级到最新版本：pip install --upgrade easy-tdx。该问题是因为 ETF、指数等品种报价精度为 3 位小数（厘），而之前按 2 位小数（分）解析导致。
• 连接不稳定或掉线：
  • 设置心跳保活机制，避免长时间闲置断开连接。
  • 避免在极短时间内高频批量请求数据，这可能会触发服务器的临时风控，导致 IP 被封禁。建议在循环请求中加入适当的随机延时（如 time.sleep(random.uniform(0.5, 1.5))）。

---

7. 总结

easy_tdx 通过以下特性，极大地降低了量化分析的门槛：

特性	说明
零门槛数据获取	一行 pip install，无需注册，无需 API Key，直接获取毫秒级行情
多维度分析能力	34 个技术指标、缠论分析、54 个内置回测策略、25 项绩效指标与 S-D 评级
可视化与 AI 友好	一条命令启动 Web 终端；所有 CLI 命令输出 JSON，天然适配 AI Agent
完全开源免费	MIT 协议，可自由使用、修改和分发

重要免责声明：本系统仅用于学习和研究目的，所有分析结果仅供参考，不构成投资建议。投资有风险，入市需谨慎。