nextmv-py 中文导航

原文: Nextmv Python SDKs
分类: 优化决策/Python SDK
大小: 11 MB
语言: Python

---

📚 项目简介

nextmv-py 是 Nextmv 平台的 Python SDK 集合，提供与决策模型和 Nextmv Cloud API 交互的工具。包含三个核心包：nextmv(通用决策建模)、nextmv-gurobipy(Gurobi 集成)、nextmv-scikit-learn(机器学习集成)。

GitHub: https://github.com/nextmv-io/nextmv-py
PyPI: nextmv, nextmv-gurobipy, nextmv-scikit-learn
文档: https://nextmv-py.docs.nextmv.io

---

🔧 核心包

包	说明	PyPI
nextmv	通用决策建模 SDK	pip install nextmv
nextmv-gurobipy	Gurobi 模型集成	pip install nextmv-gurobipy
nextmv-scikit-learn	scikit-learn 模型集成	pip install nextmv-scikit-learn

---

📁 目录结构

nextmv-py/
├── nextmv/                     # 核心 SDK
│   ├── __init__.py
│   ├── input.py               # 输入处理
│   ├── output.py              # 输出格式化
│   ├── model.py               # 模型抽象
│   ├── run.py                 # 运行逻辑
│   └── cloud/                 # Cloud API
│       ├── api.py
│       └── auth.py
├── nextmv-gurobipy/           # Gurobi 集成
│   ├── __init__.py
│   └── gurobi.py              # Gurobi 辅助函数
├── nextmv-scikit-learn/       # sklearn 集成
│   ├── __init__.py
│   └── sklearn.py             # sklearn 辅助函数
├── examples/                  # 示例代码
├── tests/                     # 单元测试
└── README.md

---

🚀 快速开始

安装

# 核心 SDK
pip install nextmv

# Gurobi 集成
pip install nextmv-gurobipy

# scikit-learn 集成
pip install nextmv-scikit-learn

# 依赖要求
# Python 3.8+
# Gurobi (可选，用于 nextmv-gurobipy)
# scikit-learn (可选，用于 nextmv-scikit-learn)

第一个决策应用

from nextmv import Model, Input, Output

# 定义决策模型
class SimpleDecision(Model):
    def run(self, input: Input) -> Output:
        # 读取输入
        options = input.data["options"]
        scores = input.data["scores"]

        # 选择最高分选项
        best_idx = scores.index(max(scores))
        best_option = options[best_idx]

        # 返回决策
        return Output(
            data={
                "selected": best_option,
                "score": max(scores)
            }
        )

# 运行模型
if __name__ == "__main__":
    model = SimpleDecision()
    model.run()

输入/输出格式

输入 (input.json):

{
  "options": ["Option A", "Option B", "Option C"],
  "scores": [85, 92, 78],
  "constraints": {
    "max_cost": 1000
  }
}

输出 (output.json):

{
  "data": {
    "selected": "Option B",
    "score": 92
  },
  "statistics": {
    "runtime": 0.023,
    "memory": 1024
  }
}

---

📖 Gurobi 集成

背包问题示例

from nextmv import Model, Input, Output
from nextmv_gurobipy import gurobi_helper
import gurobipy as gp

class KnapsackModel(Model):
    def run(self, input: Input) -> Output:
        # 读取输入
        capacity = input.data["capacity"]
        items = input.data["items"]  # [{id, weight, value}, ...]

        # 创建 Gurobi 模型
        m = gp.Model("knapsack")

        # 决策变量：是否选择物品 i
        x = m.addVars(len(items), vtype=gp.GRB.BINARY, name="x")

        # 目标：最大化总价值
        m.setObjective(
            gp.quicksum(items[i]["value"] * x[i] for i in range(len(items))),
            gp.GRB.MAXIMIZE
        )

        # 约束：总重量不超过容量
        m.addConstr(
            gp.quicksum(items[i]["weight"] * x[i] for i in range(len(items))) 
            <= capacity
        )

        # 求解
        m.optimize()

        # 提取解
        selected = [
            items[i]["id"] for i in range(len(items)) if x[i].x > 0.5
        ]
        total_value = m.objVal
        total_weight = sum(
            items[i]["weight"] for i in range(len(items)) if x[i].x > 0.5
        )

        return Output(
            data={
                "selected_items": selected,
                "total_value": total_value,
                "total_weight": total_weight
            }
        )

---

📖 scikit-learn 集成

预测 + 优化示例

from nextmv import Model, Input, Output
from nextmv_sklearn import sklearn_helper
import joblib

class DemandForecastingModel(Model):
    def run(self, input: Input) -> Output:
        # 加载预训练模型
        model = joblib.load("demand_forecaster.pkl")

        # 特征数据
        features = input.data["features"]

        # 预测需求
        predicted_demand = model.predict([features])[0]

        # 基于预测做库存决策
        safety_stock = predicted_demand * 0.2  # 20% 安全库存
        reorder_point = predicted_demand * 1.5  # 1.5 倍日需求

        return Output(
            data={
                "predicted_demand": predicted_demand,
                "safety_stock": safety_stock,
                "reorder_point": reorder_point,
                "order_quantity": predicted_demand * 7 - safety_stock
            }
        )

---

💡 典型应用场景

1. 路径优化

from nextmv import Model, Input, Output

class VehicleRouting(Model):
    def run(self, input: Input) -> Output:
        # 客户位置
        locations = input.data["locations"]
        # 车队规模
        num_vehicles = input.data["num_vehicles"]
        # 仓库位置
        depot = input.data["depot"]

        # 使用 OR-Tools 求解 VRP
        routes = solve_vrp(locations, num_vehicles, depot)

        return Output(
            data={
                "routes": routes,
                "total_distance": calculate_total_distance(routes)
            }
        )

2. 资源分配

class ResourceAllocation(Model):
    def run(self, input: Input) -> Output:
        # 项目需求
        projects = input.data["projects"]
        # 可用资源
        resources = input.data["resources"]
        # 优先级权重
        priorities = input.data["priorities"]

        # 线性规划求解
        allocation = solve_allocation(
            projects, resources, priorities
        )

        return Output(
            data={
                "allocation": allocation,
                "utilization": calculate_utilization(allocation)
            }
        )

3. 调度优化

class ShiftScheduling(Model):
    def run(self, input: Input) -> Output:
        # 班次需求
        shift_requirements = input.data["shift_requirements"]
        # 员工可用性
        employee_availability = input.data["availability"]
        # 劳动法约束
        labor_rules = input.data["labor_rules"]

        # 整数规划求解
        schedule = solve_scheduling(
            shift_requirements,
            employee_availability,
            labor_rules
        )

        return Output(
            data={
                "schedule": schedule,
                "coverage_rate": calculate_coverage(schedule)
            }
        )

---

🔗 部署到 Nextmv Cloud

1. 打包应用

# 安装 nextmv CLI
curl -fsSL https://get.nextmv.io | bash

# 登录
nextmv login

# 打包应用
nextmv app bundle \
  --name my-decision-app \
  --version 1.0.0

2. 部署应用

# 部署到 Cloud
nextmv app push \
  --app my-decision-app \
  --version 1.0.0

3. 调用 API

# 运行决策
nextmv run my-decision-app:1.0.0 \
  --input input.json \
  --output output.json

---

📚 相关资源

• community-apps - Nextmv 应用示例
• or-tools - Google OR-Tools
• pulp - Python 线性规划

---

🎓 学习路径

1. Hello World → 理解 SDK 基础
2. 简单决策 → 输入/输出处理
3. Gurobi 集成 → 优化建模
4. sklearn 集成 → 预测 + 优化
5. 部署到 Cloud → 生产化

---

本地路径: /workspace/code-examples/nextmv-py/
创建时间: 2026-06-02
难度: ⭐⭐⭐ (中级)

---

**nextmv-py 中文导航 | 决策优化 Python SDK** [返回代码索引](../../README_UPDATED.md) | [决策科学资源大全](../../docs/resources/decision-science-comprehensive-resources.md)