基金组合风险如何避免“一个分数说风险”，关键不是完成一次调用，而是让输入口径、处理状态和结果证据可以复核。本文围绕“如何校验基金持仓权重和历史样本，并解释组合波动、回撤、VaR 与风险贡献”给出一套面向真实业务流程的实现方式。
问题与结果
组合指标与数据质量同时展示，不可用基金、样本不足和陈旧数据不会被一个总分掩盖。
适用场景
- 基金组合风险看板
- 资产配置复盘
- 历史风险和分散度分析
实现前先确定边界
- 基金代码以字符串保存，避免丢失前导零
- 权重和误差必须在请求前校验
- AnalysisStatus、CoverageRatio 和 NoDataReasons 与指标同等重要
请求前先验证组合
持仓数量、基金代码、权重、分析周期和置信水平应在客户端先校验。基金代码可先通过 基金信息列表核对，并始终保持六位字符串；权重全部大于零且总和满足接口允许误差。
from math import isclose def validate_positions(positions: list[dict]) -> None: if not 2 <= len(positions) <= 10: raise ValueError("positions must contain 2 to 10 funds") codes = [item["FundCode"] for item in positions] if len(codes) != len(set(codes)): raise ValueError("fund codes must be unique") if not all(isinstance(code, str) and len(code) == 6 and code.isdigit() for code in codes): raise ValueError("fund codes must be six-digit strings") if not all(item["Weight"] > 0 for item in positions): raise ValueError("weights must be positive") if not isclose(sum(item["Weight"] for item in positions), 1.0, abs_tol=1e-6): raise ValueError("weights must sum to one")调用与结果读取
curl -X POST "https://api.gugudata.com/ai/fund/portfolio-risk-analyses" \ -H "Authorization: Bearer YOUR_APPKEY" \ -H "Content-Type: application/json" \ -d '{"Positions":[{"FundCode":"012729","Weight":0.6},{"FundCode":"110022","Weight":0.4}],"Period":"1Y","ConfidenceLevel":0.95}'基金组合风险分析的 基金组合风险分析的 基金组合风险分析的 HTTP 和业务状态成功后，仍需检查Data.AnalysisStatus。报告同时展示样本区间、观察数、覆盖率、最新数据年龄和警告，再展示波动、最大回撤、VaR、CVaR、相关性和风险贡献。
任务状态与失败处理
生产接入至少区分INPUT_INVALID、PENDING、RUNNING、SUCCEEDED、PARTIALLY_FAILED和FAILED。状态名称可以按业务调整，但不能把“任务已创建”“请求 HTTP 成功”和“结果可用”合并成一个成功状态。
参数错误应直接返回给调用方；频率或额度限制停止当前批次并保留下一次可执行条件；依赖服务失败可以进入有上限的退避重试；业务结果缺失、覆盖不足或引用不足则进入人工复核。每次尝试记录请求标识、开始和结束时间、业务状态、失败原因以及是否产生可用结果。
还应为重试设置幂等键和最大次数。相同输入、相同规则版本和相同业务目标不能因为网络超时重复写入多个正式结果；超过重试上限后保留最后错误和人工处理入口。
运行记录与回归检查
上线前保存一组脱敏固定样本，用于比较接口或规则升级前后的字段结构、状态流转和关键结果。回归测试不追求结果文本逐字一致，而是检查必填字段、来源证据、错误分类和能力边界是否稳定。
对于本文场景，重点回归以下约束：
- 基金代码以字符串保存，避免丢失前导零
- 权重和误差必须在请求前校验
- AnalysisStatus、CoverageRatio 和 NoDataReasons 与指标同等重要
监控指标至少包括成功结果数、失败数、处理中任务数、人工复核数和数据新鲜度。任何未采样指标都应显示“未采样”，不能默认为零。
数据契约与留痕
| 字段 | 作用 |
|---|---|
portfolio_id | 稳定业务标识，用于关联记录和请求追踪 |
positions | 业务数据字段，保存来源、口径和缺失状态 |
period | 业务数据字段，保存来源、口径和缺失状态 |
confidence_level | 业务数据字段，保存来源、口径和缺失状态 |
analysis_status | 显式状态或原因，禁止以空值代替失败 |
observation_count | 业务数据字段，保存来源、口径和缺失状态 |
coverage_ratio | 业务数据字段，保存来源、口径和缺失状态 |
portfolio_metrics | 业务数据字段，保存来源、口径和缺失状态 |
fund_metrics | 业务数据字段，保存来源、口径和缺失状态 |
no_data_reasons | 业务数据字段，保存来源、口径和缺失状态 |
重试应新增尝试记录，不覆盖最后一次失败。派生结果必须关联输入版本、生成时间和业务状态。
验收清单
能力边界
历史风险指标描述过去样本，不预测未来收益，也不构成投资建议或资产配置结论。
示例中的YOUR_APPKEY仅为占位符。真实密钥只能放在服务端环境变量或密钥管理系统中。
