《SoftwareX》：EvaalAPI: A web service for the real-time offsite evaluation of the IPIN indoor localization competition
编辑推荐：
在真实条件下评估室内定位与导航系统的性能是一项重大挑战。室内定位与室内导航（IPIN）竞赛依托EvAAL框架，以确保公平、真实的基准测试。在IPIN竞赛的早期版本中，离场评估赛道的参赛者被要求对预录制的多传感器数据进行离线处理。这种安排使得定位可以被视为一个批
在真实条件下评估室内定位与导航系统的性能是一项重大挑战。室内定位与室内导航（IPIN）竞赛依托EvAAL框架，以确保公平、真实的基准测试。在IPIN竞赛的早期版本中，离场评估赛道的参赛者被要求对预录制的多传感器数据进行离线处理。这种安排使得定位可以被视为一个批处理优化问题。参赛算法经常利用非因果的前向知识和迭代轨迹平滑技术，导致与物理现场试验相比出现不切实际的精度提升。为解决这些失真问题，我们引入了EvaalAPI——一种能够模拟室内定位原始数据实时供应的Web服务。在在线模式下，EvaalAPI通过强制传感器数据的因果处理、禁止试验重启（单次操作）以及通过漏桶超时算法模拟实时执行，迫使参赛算法模拟物理部署行为。该服务的引入有效地弥合了理论后处理精度与现实系统极限之间的差距。EvaalAPI支持在线（实时）和离线（批处理）两种评估模式。
EvaalAPI：弥合室内定位评估理论与现实差距的实时仿真服务
一、研究背景与问题提出
随着基于位置服务的普及，室内环境中的导航与上下文感知应用需求激增。然而，由于复杂的信号衰减和多径传播效应，室内空间中用户位置的精确估计仍是关键挑战。IPIN竞赛依托EvAAL框架，为室内定位解决方案提供严格的基准测试环境，确保真实条件、相同路径和自然行人运动，从而为室内定位算法的透明比较提供公平、严谨、真实的环境。
竞赛由现场赛道（参赛者在环境中实时行走）和离场赛道（处理赛道主席提供的预录多传感器数据）组成。在2015至2020年间举办的竞赛中，离场传感器数据以静态时间戳文件形式分发给参赛者。这导致软件工程师和研究人员将离场赛道视为标准批处理优化问题。由于整个数据集可一次性获取，定位算法能够利用前向数据（非因果处理）并迭代修正整条轨迹上的历史错误。这造成了不切实际的优异定位性能——例如，2020年离场智能手机赛道的获胜分数达到1.0米（赛道3）和0.5米（赛道4），远超同期相同环境中现场竞赛记录的3至4米真实误差。竞赛需要一种能够正确模拟部署于实际设备上的真实跟踪系统的方法，这类系统具有因果性（当前位置必须仅依据过去和当前的传感器读数估计）和单次性（系统故障无法由用户追溯性重启或修复）特征。EvaalAPI正是为弥合这一架构鸿沟、强制在线竞赛与EvAAL框架保持一致而引入的。
二、研究内容与核心结论
EvaalAPI是基于Python Flask框架的Web服务，支持两种对应不同IPIN赛道的执行模式：在线试验（模拟实时因果系统）和离线试验（模拟批处理应用）。代码库设计轻量且易于参赛者和竞赛主席部署，包含完整的OpenAPI描述文档。核心服务器代码evaalapi.py负责HTTP路由、试验状态管理和漏桶逻辑，试验参数（如减速因子V、松弛阈值S和原始传感器数据文件路径）在YAML试验配置文件中定义。
在安全方面，客户端隔离机制通过使用唯一的字母数字"试验名称"实现，该名称由组织者安全分发给各参赛团队。团队试验名称充当唯一令牌，猜测或访问其他团队试验名称在数学上可通过适当选择长度使其概率趋近于零，所有此类尝试均被服务器记录。速率限制可配置，默认通过拒绝高于实时速率（默认每秒两次请求）的客户端请求（代码423）来强制执行。TLS保护取决于Web服务器配置。
在容错方面，服务器或网络侧故障可能不公平地影响参赛者表现。早期曾出现持续数分钟的网络中断，超出漏桶超时机制可掩盖的范围。对此，组织者通过调整超时参数、审查代码、建议更换网络节点或使用VPN等措施解决。近年来，EvaalAPI服务器部署于欧洲、中国、日本等多个地点，将网络问题减少至少数案例。服务器因软件错误、配置错误或资源不足导致的故障未做处理，但可通过事后人工检查服务器行为和日志识别，并手动重启受影响试验。
在线评估的核心功能在于强制因果性：通过轮询循环反复发出/nextdata命令，客户端提供当前估计位置坐标和期望时间范围，服务器记录提交位置、推进虚拟试验时间戳，并返回对应时间窗口的传感器数据行。此机制强制客户端仅能依据该时间之前的传感器数据计算当前位置。实时行为通过虚拟时间管理，虚拟时间是墙钟时间的缩放模拟，缩放比例为减速因子V（竞赛中通常设为2），使客户端仅需达到仿真系统速度的一半。当客户端过慢时，试验被中断（代码405）。漏桶算法通过松弛时间阈值S（通常设为15秒）补偿网络延迟波动，当剩余松弛时间超过S时溢出并封顶，低于0时排空并返回405代码，模拟实时跟踪引擎中的严重硬件或处理故障。离线评估模式则支持特定赛道（如IPIN 2025赛道7：5G CIR）的批处理需求，客户端一次性下载全部传感器数据，在截止期限前本地计算完整轨迹并上传全部时间戳估计值。
软件架构采用状态驱动设计，试验状态机从非启动状态转换至运行状态，最终到达完成或超时状态。为强制单次行为，EvaalAPI区分测试试验（提供地面真值，可通过/reload端点重置）和计分试验（不可重载，重载请求返回HTTP 422错误并永久锁定，计为失败）。API设计简化客户端实现：在线模式仅使用HTTP GET请求，离线模式使用POST请求。
三、关键技术方法
研究人员采用的主要技术方法包括：基于Python Flask框架的Web服务架构，实现HTTP路由、试验状态管理和漏桶逻辑；在线模式通过/nextdata轮询循环强制因果性处理，客户端仅能基于过去和当前传感器数据计算位置；通过虚拟时间缩放（减速因子V）和漏桶超时算法（松弛阈值S）模拟实时执行约束；采用状态机驱动的试验生命周期管理，区分可重置的测试试验与不可重置的计分试验；使用唯一字母数字试验名称实现客户端隔离，避免使用Cookie。
四、研究结果
4.1 在线评估：强制因果性。 通过/nextdata命令的轮询循环，服务器记录客户端提交的位置坐标，推进虚拟时间戳，并返回对应时间窗口的传感器数据，强制客户端仅能利用当前时刻之前的传感器数据计算位置估计，消除非因果前向知识利用。
4.2 在线评估：强制实时行为。 通过虚拟时间机制和漏桶算法，服务器以减速因子V缩放墙钟时间，当客户端处理速度过慢导致松弛时间耗尽时返回405代码中断试验，模拟真实硬件故障。漏桶算法公式为s = s + Vh - (c - p)，当s超过阈值S时溢出封顶，低于0时超时中断。
4.3 离线评估：受约束的批处理。 客户端通过GET/TRIAL/nextdata?offline一次性下载全部传感器数据，本地计算完整轨迹后通过POST/TRIAL/estimates批量上传时间戳估计值，必须在允许的执行时间阈值内完成。
4.4 试验状态机与单次限制。 试验从非启动状态转换至运行状态，最终到达完成或超时状态。测试试验可通过/reload端点重置，而计分试验不可重载，重载请求返回422错误并永久锁定。
4.5 Web服务API。 在线模式仅使用HTTP GET请求，离线模式使用POST请求，此架构选择简化客户端实现，降低HTTP动词开销，便于紧密轮询循环的客户端侧实现。
五、影响与结论
EvaalAPI的引入纠正了2021年前离场定位竞赛中的基准测试失真。2021年赛道3和赛道4引入因果实时处理要求后，参赛者获得的结果显著更贴近现实——2021年赛道3获胜定位误差为真实的4.4米第三四分位误差，与此前及此后现场物理基准（赛道1）获胜系统的历史误差高度一致。自2021年以来，该软件持续支持从标准100Hz智能手机IMU到复杂视觉和信道冲激响应（CIR）数据环境的多传感器数据类型，已作为核心评估引擎服务53个参赛团队。EvaalAPI已被中国科学院、根特大学、华为技术、南洋理工大学、伦敦玛丽女王大学等欧洲、亚洲和美洲的顶尖学术与工业研究团队采用。此外，PDR基准标准化委员会已采用EvaalAPI用于xDR Challenge 2025，确认其作为国际室内定位研究界强制执行严格、可复制、公平评估的标准工具地位。
六、研究结论
EvaalAPI是一种成熟的基于真实数据集的定位与跟踪算法现实评估Web接口。该软件为研究人员提供了稳健的工具，以验证其定位架构是否在结构上适用于现实场景部署，从而有助于缩小实验室算法与商业可行性之间的差距。通过强制因果性、通过漏桶算法约束实时计算，并严格执行不可重载的单次限制，它防止了过拟合和算法捷径，因此适用于科学竞赛。
