rofrano/kstar

KStar Service 镜像文档

镜像概述和主要用途

KStar Service是一款集成K*算法的先进Top-k规划器，基于Fast Downward框架开发。本镜像作为ctpelok77/kstar的分支版本，在保留核心规划功能的基础上，新增了REST API服务，支持远程调用规划能力，可作为独立工具或服务集成到各类应用中。

核心功能和特性

• Top-k规划能力：采用K*算法，支持生成指定数量（k值）的规划方案
• Fast Downward集成：基于Fast Downward规划系统，具备高效的规划性能
• REST API支持：提供远程调用接口，方便集成到分布式系统或第三方应用
• API兼容性：与ctpelok77/ibmresearchaiplanningsolver API保持一致，支持无缝替换
• 多运行模式：支持本地命令行运行和后台服务两种部署方式
• Swagger UI：内置API文档界面，便于接口调试和使用（需配置环境变量）

使用场景和适用范围

• 本地规划任务：科研人员或开发者在本地执行规划算法测试与验证
• 远程服务集成：需要规划能力的应用通过API远程调用规划器
• 学术研究：用于Top-k规划算法相关的学术实验和性能评估
• PDDL问题求解：处理符合PDDL（规划域定义语言）格式的规划问题

使用方法和配置说明

本地Docker运行

通过Docker在本地运行容器，挂载当前目录并使用bash交互：

sh
docker run --rm -it -v $(pwd):/work rofrano/kstar bash

容器内使用方法

在容器内执行规划命令的基本格式：

sh
/usr/bin/python3 /workspace/kstar/fast-downward.py --build release64 <domain_file> <problem_file> --search "kstar(heuristic,k=<number-of-plans>)"

示例（使用https://github.com/rofrano/kstar%E4%B8%AD%E7%9A%84%E7%A4%BA%E4%BE%8B%E6%96%87%E4%BB%B6%EF%BC%89%EF%BC%9A

sh
/usr/bin/python3 /workspace/kstar/fast-downward.py --build release64 examples/gripper/domain.pddl examples/gripper/prob01.pddl --search "kstar(blind(),k=100)"

作为服务运行

将KStar部署为后台服务，提供REST API接口：

sh
docker run -d -p 4501:4501 \
    --env server__hostname=`hostname`:4501 \
    --name <YOUR_CONTAINER_NAME> rofrano/kstar

参数说明：

• -d：后台运行容器
• -p 4501:4501：端口映射，将容器的4501端口映射到主机的4501端口
• --env server__hostname：可选环境变量，用于配置Swagger UI绑定的主机名和端口（如无需使用Swagger UI可省略）
• --name：指定容器名称（如kstar或planner），便于后续管理（如docker stop kstar、docker start kstar）

服务使用示例

通过REST API远程调用规划器，以下是使用curl的示例：

sh
url=http://localhost:4501/planners/topk/kstar-topk
domain=`sed 's/;/\n;/g' <DOMAIN-FILE> | sed '/^;/d' | tr -d '\n'`
problem=`sed 's/;/\n;/g' <PROBLEM-FILE> | sed '/^;/d' | tr -d '\n'`
body="{\"domain\": \"$domain\", \"problem\": \"$problem\", \"numplans\":<NUMBER-OF-PLANS>}"
basebody=`echo $body`
curl -d "$basebody" -H "Content-Type: application/json" "$url"

参数说明：

• <DOMAIN-FILE>：PDDL域文件路径（如domain.pddl）
• <PROBLEM-FILE>：PDDL问题文件路径（如problem.pddl）
• <NUMBER-OF-PLANS>：需生成的规划数量（正整数）

响应示例（以gripper问题为例）：

json
{
    "plans": [
        {
            "cost": 11,
            "actions": [
                "pick ball2 rooma left",
                "pick ball1 rooma right",
                "move rooma roomb",
                "drop ball1 roomb right",
                "drop ball2 roomb left",
                "move roomb rooma",
                "pick ball3 rooma left",
                "pick ball4 rooma right",
                "move rooma roomb",
                "drop ball3 roomb left",
                "drop ball4 roomb right"
            ]
        }
    ]
}

引用

Michael Katz, Shirin Sohrabi, Octavian Udrea and Dominik Winterer
A Novel Iterative Approach to Top-k Planning [[pdf]]([***] [bib]
In ICAPS 2018

联系

如有问题和建议，请联系Michael Katz（***）。