SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场oransim-causal-marketing-twin

oransim-causal-marketing-twin

营销与增长

查看项目

更新于 10-15 18:38

技能介绍

Oransim 是一个面向营销团队的开源因果仿真引擎，核心目标是在实际花钱之前，对营销活动进行预测、反事实推演与因果审计。

用途 Oransim 用于营销活动的因果数字孪生模拟。它让团队能够预测活动 ROI、运行反事实“假设”场景（更换 KOL、重新分配预算、切换平台），并通过透明的 64 节点因果图审计每一次预测。

主要能力

  • 预投放 ROI 排名：覆盖创意 × KOL × 预算组合。
  • 投放中 do() 算子推演：例如第 3 天更换 KOL，查看 14 天路径差异。
  • 事后反事实分析：例如“如果当时投小红书而不是抖音会怎样”。
  • 基于 LLM 的“灵魂人设”（soul personas），支持 100 万以上虚拟消费者智能体。
  • 因果神经 Hawkes 过程（Causal Neural Hawkes Process）用于时间级联模拟。
  • 每臂反事实头（TARNet / Dragonnet 架构）。

安装 代码仓库：https://github.com/OranAi-Ltd/oransim.git

git clone https://github.com/OranAi-Ltd/oransim.git cd oransim pip install -e '.[dev]'

启动后端（mock 模式，无需 API key） LLM_MODE=mock python -m uvicorn oransim.api:app --port 8001

启动后端（真实 LLM 管线） LLM_MODE=api
LLM_API_KEY=$YOUR_LLM_API_KEY
LLM_MODEL=gpt-4o
python -m uvicorn oransim.api:app --port 8001

启动前端 python -m http.server 8090 --directory frontend

打开 http://localhost:8090

配置 所有配置通过环境变量完成（参见 .env.example）：

  • LLM_MODE："mock"（确定性桩）或 "api"（真实 LLM）
  • LLM_PROVIDER：openai（默认）、anthropic、gemini、qwen
  • LLM_API_KEY：API 密钥（也接受 OPENAI_API_KEY、ANTHROPIC_API_KEY 等提供商专属变量）
  • LLM_MODEL：模型名称
  • LLM_BASE_URL：自定义基础 URL（DeepSeek、vLLM 等）

提供商快速参考：

  • OpenAI：LLM_PROVIDER=openai，LLM_BASE_URL=https://api.openai.com/v1，示例模型 gpt-4o
  • DeepSeek：LLM_PROVIDER=openai，LLM_BASE_URL=https://api.deepseek.com/v1，示例模型 deepseek-chat
  • vLLM（本地）：LLM_PROVIDER=openai，LLM_BASE_URL=http://localhost:8000/v1，任意模型
  • Anthropic：LLM_PROVIDER=anthropic，默认 base URL，示例模型 claude-sonnet-4-6
  • Gemini：LLM_PROVIDER=gemini，默认 base URL，示例模型 gemini-2.5-flash
  • Qwen：LLM_PROVIDER=qwen，默认 base URL，示例模型 qwen-plus

主要 API 端点 所有端点位于 http://localhost:8001。

POST /api/predict — 运行活动模拟 payload 包含 campaign（name、platform、budget、duration_days、creatives、kols、budget_split）、mode（"fast" 分位数基线或 "full" LLM 智能体模拟）、n_simulations。返回 roi 的 p50、p35、p65 以及 causal_path。

GET /api/graph/inspect — 审计因果图 返回节点数（64）与边数（117），可遍历从预算分配到购买意图的路径。

POST /api/sandbox/counterfactual — 投放中 KOL 更换 传入 base_campaign_id、intervention（do 中指定 remove/add KOL、day、budget_realloc）、rollout_days。返回 roi_diff、trajectory_diff、attribution。

POST /api/sandbox/postmortem — 平台反事实 传入 actuals（campaign_id、spend、observed_roi）与 counterfactual_alloc。返回 counterfactual_roi 与 delta。

GET /api/adapters — 列出可用平台适配器 返回如 ["xhs_v1", "tiktok_agent", "douyin", ...]。

Python SDK 直接使用引擎 可从 oransim.world_model 导入 AgentSociety，从 oransim.causal 导入 CausalGraph、do_operator，从 oransim.diffusion 导入 HawkesRollout。流程为：构建因果图、初始化虚拟消费者社会、定义活动、运行基线模拟、应用 do() 算子干预并对比反事实结果。

预投放 ROI 排名 使用 itertools.product 遍历创意、KOL 列表与预算组合，对每个组合运行 HawkesRollout，收集 roi_p35、roi_p50、roi_p65，并用 pandas 排序取前 5。

常见模式

  • Mock 模式用于 CI / 测试：设置 LLM_MODE=mock，所有 LLM 调用返回确定性桩，快速、免费、可复现。
  • 检查后端是否处于 mock 模式：请求 /health，若 llm_mode 为 mock 则提示警告。
  • 检查预测的因果路径：遍历 result["causal_path"] 打印节点 id、weight、layer。
  • 加载 LightGBM 分位数基线（fast 模式）：从 models/lgbm_quantile_baseline.pkl 加载，特征向量为 [budget, n_kols, avg_fans, duration_days, platform_enc]，预测 p35、p50、p65。

项目结构 oransim/ 下包含：api.py（FastAPI 应用）、api_routers/（predict、sandbox、graph、adapters 路由）、causal/（SCM、do() 算子、64 节点图、Pearl 三步）、world_model/（AgentSociety、IPF 人口合成、灵魂人设）、diffusion/（因果神经 Hawkes 过程 14 天推演）、adapters/（平台适配器）；frontend/（index.html 与模块化 JS）；configs/default_graph.yaml（64 节点 / 117 边因果图定义）；models/lgbm_quantile_baseline.pkl；data/（21k 笔记开源演示语料）；docs/en/quickstart.md；.env.example。

故障排查

  • 即使设置了 API key 后端仍返回 mock 数据：检查前端黄色横幅，确认环境变量已导出（echo $LLM_MODE 应为 "api"，echo $LLM_API_KEY 应非空），设置后需重启服务器。
  • ModuleNotFoundError: oransim：在仓库根目录以可编辑模式安装 pip install -e '.[dev]'。
  • 模拟超时（> 120s）：减少智能体数量或使用 fast 模式，如 {"mode": "fast", "n_simulations": 30}，或减小 AgentSociety 规模。
  • 浏览器调用 API 出现 CORS 错误：FastAPI 应用已为 localhost:8090 配置 CORS 中间件；若使用其他端口，可更新 origins 列表或设置 CORS_ORIGINS。
  • 反事实结果与基线相同：mock 模式下属预期，桩是确定性的；切换到 LLM_MODE=api 才能让基线与干预臂产生真实差异。

企业数据访问 开源语料为 21k 笔记。生产规模数据（430 万+ 小红书笔记、210 万+ 创作者）可通过 datacenter.oran.cn 浏览，或联系 cto@orannai.com。

关键概念

  • do() 算子：Pearl 的干预算子——将变量设为某值，切断其入边。
  • 灵魂人设（Soul persona）：基于 LLM 的智能体人格，读取真实创意并决定互动。
  • Hawkes 推演：自激点过程，模拟 14 天内社交分享的级联。
  • P35/P50/P65：ROI 的置信区间，不是点估计，始终是分布。
  • KOL 层级：Top（>100 万粉丝）、Mid（5 万–100 万）、KOC（1 千–5 万）、长尾（<1 千）。
  • fast 模式：LightGBM 分位数基线，数秒完成，无 LLM 调用。
  • full 模式：带 LLM 灵魂人设的完整智能体模拟，需数分钟，要求 LLM_MODE=api。

适用场景 适用于营销团队在投放前评估创意、KOL 与预算组合的 ROI，投放中评估更换 KOL 等干预的影响，以及投放后进行平台与预算分配的反事实复盘。

限制 开源语料规模为 21k 笔记，生产级数据需另行获取；mock 模式下反事实结果与基线一致；full 模式依赖 LLM API 且耗时较长；模拟可能超时，需降低智能体数量或使用 fast 模式。