人工智能大模型模型推理服务后端【免费下载链接】MooncakeMooncake is the serving platform for Kimi, a leading LLM service provided by Moonshot AI.项目地址https://gitcode.com/gh_mirrors/mo/Mooncake点击查看免费下载导读Mooncake 是 Moonshot AIKimi 背后的大模型服务的分布式 KVCache 与传输服务平台其两大核心组件——TransferEngine高速数据传输引擎与 Mooncake Store分布式对象存储——在执行各类 API 时都会返回统一的错误码。本篇指南基于 error-code.md 系统梳理两大组件的错误码分组、数值与含义并结合 error.h、types.h 等源码解释错误码的产生路径与排查方向。读完本文你将能在实际开发与排障中快速定位 API 返回值对应的失败原因并理解错误码在 C 客户端与 Python 封装层之间的传递方式。错误码设计总览Mooncake 的错误码遵循一个核心约定对于绝大多数 API返回值本身就代表错误原因。正常执行返回0任何非零值均对应一种失败场景。两大组件各自维护独立的错误码体系TransferEngine使用宏定义分散在mooncake-transfer-engine/include/error.h按ERR_前缀命名分为参数错误 / 握手 / 其他三个大组Mooncake Store使用enum class ErrorCode定义于mooncake-store/include/types.h采用负整数区间分段设计每类错误占用一段连续数值范围例如 Segment 选择类为 -100-199便于快速按数值区间判断错误类型。Store 的枚举还配套提供了三个转换工具函数见 types.cpptoString()将错误码映射为可读字符串、toInt()转为int32_t、fromInt()反向转换客户端与 RPC 层均通过它们完成错误码的序列化与展示。Mooncake TransferEngine 错误码详解TransferEngine 的错误码定义在 error.h宏形式共 4 组、17 个错误码。下表按官方文档分组完整列出分组返回值说明正常0正常执行参数错误ERR_INVALID_ARGUMENT (-1)输入参数不正确无法细分为本组其他项时ERR_TOO_MANY_REQUESTS (-2)调用SubmitTransfer接口时传入的请求数超过该BatchID分配时指定的最大值ERR_ADDRESS_NOT_REGISTERED (-3)请求中的源地址和/或目标地址未注册含本地已注册但尚未上传到元数据服务器的情况ERR_BATCH_BUSY (-4)回收一个正在执行请求的BatchIDERR_DEVICE_NOT_FOUND (-6)没有可用的 RDMA 设备来执行用户请求ERR_ADDRESS_OVERLAPPED (-7)重复注册相互重叠的内存区域握手ERR_DNS (-101)本地服务器名不是合法的 DNS 主机名或 IP 地址导致其他节点无法与该节点握手ERR_SOCKET (-102)握手过程中与 TCP Socket 相关的错误ERR_MALFORMED_JSON (-103)握手交换过程中数据格式错误ERR_REJECT_HANDSHAKE (-104)对端因自身错误拒绝握手其他ERR_METADATA (-200)与元数据服务器通信失败ERR_ENDPOINT (-201)RdmaEndPoint对象创建和使用过程中的异常ERR_NUMA (-300)系统不支持 numa 接口ERR_CLOCK (-301)系统不支持clock_gettime接口ERR_MEMORY (-302)内存不足源码补充说明实际 error.h 中还定义了文档未提及的ERR_BATCH_CLEANUP_DEFERRED (-5)、ERR_CONTEXT (-202)、ERR_NOT_IMPLEMENTED (-303)用于批处理延迟清理、上下文错误与未实现功能等场景遇到这三个返回值同样属于正常错误体系。参数错误组-1 ~ -7的触发路径ERR_TOO_MANY_REQUESTS与传输请求的批处理机制直接相关。每次allocateBatchID会指定该批次可容纳的最大请求数提交时若超出上限即触发该错误。从源码结构看sender_credit.h 中累计信用额度不足时也会返回该错误码反映的是请求数量超过配额的统一语义。ERR_ADDRESS_NOT_REGISTERED传输地址必须在注册后方可使用。transfer_metadata.cpp 在本地元数据查无匹配项时返回该错误transfer_engine_impl.cpp 对非该错误的注册返回还会做额外处理说明它同时承担本地未注册与未同步到远端元数据两种语义。排查建议检查registerLocalMemory/registerRemoteMemory是否成功调用以及注册信息是否已通过元数据插件如 Redis发布。ERR_DEVICE_NOT_FOUNDtopology.cpp 在按存储类型查找传输路径时找不到可用 RDMA 设备即返回该错误。排查建议确认rdma_devices配置与实际硬件是否一致运行show_link示例example/show_link.cpp查看拓扑矩阵是否正常构建。ERR_ADDRESS_OVERLAPPEDtransfer_engine_impl.cpp 在注册重叠内存区间时返回。排查建议检查多次registerLocalMemory的地址区间是否存在交叠避免重复注册同一段内存。握手组-101 ~ -104的触发路径握手错误集中在节点间的 P2P 建连阶段。从源码看ERR_DNStransfer_metadata_plugin.cpp 在解析对端主机名失败时返回核心要求是本地服务器名必须是合法 DNS 主机名或 IPERR_SOCKETcommon.h 与元数据插件中的 TCP 连接建立、读写失败均归入此类网络不通、端口未监听是常见诱因ERR_MALFORMED_JSONtopology.cpp 在解析对端拓扑 JSON 失败时返回通常意味着握手消息格式不兼容或序列化版本不一致ERR_REJECT_HANDSHAKE对端因自身状态异常主动拒绝连接。排查建议优先检查集群中所有节点的主机名解析/etc/hosts或 DNS、防火墙规则与监听端口并确认各节点版本一致。其他组-200 ~ -302的触发路径ERR_METADATA (-200)元数据服务器Redis 等不可达或操作失败时transfer_metadata.cpp 多处返回该错误。在启用 TENT 兼容层时transfer_engine.cpp 会把kMetadataError、kInvalidMetadataType、kNeedsRefreshCache统一映射为ERR_METADATAERR_NUMA (-300)common.h 中的bindToSocket在非 Linux 平台或numa_available() 0时返回用于 CPU 绑核场景ERR_CLOCK (-301)common.h 中的getCurrentTimeInNano在clock_gettime调用失败时返回ERR_MEMORY (-302)multi_transport.cpp 在批处理描述符分配失败时返回对应 OOM 场景。此外值得留意 transfer_engine.cpp 中的tentToClassicError函数当启用 TENT 传输后端时TENT 内部的状态码会被统一映射为经典错误码保证上层 API 的错误语义不随后端实现变化。Mooncake Store 错误码详解Store 的错误码以enum class ErrorCode定义于 types.h采用十进制的负整数值区间组织官方文档表格如下分组返回值说明正常0操作成功内部错误INTERNAL_ERROR (-1)发生内部错误缓冲区分配BUFFER_OVERFLOW (-10)缓冲区空间不足Segment 选择SHARD_INDEX_OUT_OF_RANGE (-100)Shard 索引越界SEGMENT_NOT_FOUND (-101)未找到可用 segmentSEGMENT_ALREADY_EXISTS (-102)Segment 已存在Handle 选择NO_AVAILABLE_HANDLE (-200)因空间不足导致内存分配失败版本INVALID_VERSION (-300)无效版本KeyINVALID_KEY (-400)无效 key引擎WRITE_FAIL (-500)写操作失败参数INVALID_PARAMS (-600)无效参数引擎操作INVALID_WRITE (-700)无效写操作INVALID_READ (-701)无效读操作INVALID_REPLICA (-702)无效副本操作对象REPLICA_IS_NOT_READY (-703)副本尚未就绪OBJECT_NOT_FOUND (-704)对象不存在OBJECT_ALREADY_EXISTS (-705)对象已存在OBJECT_HAS_LEASE (-706)对象持有租约LEASE_EXPIRED (-707)租约在数据传输完成前过期传输TRANSFER_FAIL (-800)传输操作失败校验和CHECKSUM_MISMATCH (-801)取回的对象数据与其存储的校验和不一致RPCRPC_FAIL (-900)RPC 操作失败高可用ETCD_OPERATION_ERROR (-1000)etcd 操作失败ETCD_KEY_NOT_EXIST (-1001)etcd 中找不到 keyETCD_TRANSACTION_FAIL (-1002)etcd 事务失败ETCD_CTX_CANCELLED (-1003)etcd 上下文被取消UNAVAILABLE_IN_CURRENT_STATUS (-1010)当前状态下无法执行请求UNAVAILABLE_IN_CURRENT_MODE (-1011)当前模式下无法执行请求文件FILE_NOT_FOUND (-1100)文件不存在FILE_OPEN_FAIL (-1101)打开文件或写入已有文件出错FILE_READ_FAIL (-1102)读文件出错FILE_WRITE_FAIL (-1103)写文件出错FILE_INVALID_BUFFER (-1104)文件缓冲区错误FILE_LOCK_FAIL (-1105)文件锁操作失败FILE_INVALID_HANDLE (-1106)无效文件句柄任务 / 作业TASK_NOT_FOUND (-1400)任务 ID 不存在或已完成任务已从 master 内存历史中被清理TASK_PENDING_LIMIT_EXCEEDED (-1401)master 端待处理任务队列已满无法接受新任务JOB_NOT_FOUND (-1402)作业 ID 不存在数值区间即错误分类从 types.h 的注释可以确认每个错误组的取值区间是刻意预留的-20 ~ -99缓冲区分配类当前仅BUFFER_OVERFLOW-100 ~ -199Segment 选择类-200 ~ -299Handle 选择类-300 ~ -399版本类-400 ~ -499Key 类-500 ~ -599引擎类-600 ~ -699参数类-700 ~ -799引擎操作与对象类-800 ~ -899传输与校验和类-900 ~ -999RPC 类-1000 ~ -1099高可用类-1100 ~ -1199文件类-1200 ~ -1299Bucket 类-1300 ~ -1399Offload 类-1400 ~ -1499任务 / 作业类-1500 ~ -1599序列化类-1600 ~ -1699DFS 类-1700 ~ -1799租户配额类这种分段设计的实用价值开发者只需看数值的百位/千位即可初步定位错误大类例如返回-70x系列必然是对象状态问题-10xx系列必然是 etcd/HA 问题。文档之外的完整错误码实际 types.h 定义的错误码比官方文档表格更全后续版本迭代新增的包括客户端/参数类CLIENT_NOT_FOUND (-103)、ILLEGAL_CLIENT (-601)对象与副本类OBJECT_HAS_REPLICATION_TASK (-708)、OBJECT_NO_REPLICATION_TASK (-709)、REPLICA_NOT_FOUND (-710)、REPLICA_ALREADY_EXISTS (-711)、REPLICA_IS_GONE (-712)、REPLICA_NOT_IN_LOCAL_MEMORY (-713)、OBJECT_REPLICA_BUSY (-714)RPC 类RPC_TIMEOUT (-901)客户端侧 deadline 命中高可用类OPLOG_ENTRY_NOT_FOUND (-1004)、K8S_LEASE_OPERATION_ERROR (-1005)、K8S_LEASE_NOT_FOUND (-1006)、INCOMPLETE_OPLOG_CATCH_UP (-1007)、NOT_SUPPORTED (-1012)Bucket / 卸载类BUCKET_NOT_FOUND (-1200)、BUCKET_ALREADY_EXISTS (-1201)、KEYS_EXCEED_BUCKET_LIMIT (-1202)、KEYS_ULTRA_LIMIT (-1203)、UNABLE_OFFLOAD (-1300)、UNABLE_OFFLOADING (-1301)序列化类SERIALIZE_UNSUPPORTED (-1500)、SERIALIZE_FAIL (-1501)、DESERIALIZE_FAIL (-1502)、PERSISTENT_FAIL (-1503)DFS 类DFS_NETWORK_TIMEOUT (-1600)、DFS_SERVICE_UNAVAILABLE (-1601)、DFS_QUOTA_EXCEEDED (-1602)、DFS_PERMISSION_DENIED (-1603)、DFS_STALE_HANDLE (-1604)、DFS_PARTIAL_WRITE (-1605)租户配额类TENANT_QUOTA_EXCEEDED (-1700)、TENANT_NOT_REGISTERED (-1701)、TENANT_NOT_EMPTY (-1702)其中TASK_NOT_FOUND的语义值得特别注意已完成的异步任务会从 master 的内存历史中被裁剪prune因此查询一个早已完成的任务 ID 也会得到该错误而非仅针对不存在的任务。types.h 中的DEFAULT_MAX_TOTAL_FINISHED_TASKS 10000等常量即控制着这一历史裁剪窗口。典型错误码的排查要点BUFFER_OVERFLOW (-10)/NO_AVAILABLE_HANDLE (-200)内存或缓冲区空间不足。types.h 中定义了辅助提示字符串建议调低eviction_high_watermark_ratio或挂载更多 segment来释放空间LEASE_EXPIRED (-707)租约在数据传输完成前过期需检查网络延迟与租约 TTL 配置如 types.h 中的 KV 租约默认 TTL 与软固定 TTLCHECKSUM_MISMATCH (-801)取回数据与存储校验和不一致属于数据完整性告警应排查传输链路RDMA 错误、内存损坏ETCD_* (-1000 系列)HA 模式下与 etcd 的交互失败检查 etcd 集群健康状态与网络连通性UNAVAILABLE_IN_CURRENT_STATUS (-1010)/UNAVAILABLE_IN_CURRENT_MODE (-1011)请求与 master 当前状态如非 HA 模式、Standby 状态不匹配需要核对 master 的运行模式配置。错误码在客户端 API 中的传递方式理解错误码如何回到调用方有助于正确解读返回值C 客户端Store 的客户端接口大量使用tl::expectedReturnType, ErrorCode返回类型见 pyclient.h错误码作为ErrorCode枚举随结果一并返回RPC 层通过toInt()/fromInt()与线上协议互转Python 封装层pyclient.h 显示参数校验失败时客户端直接以toInt(ErrorCode::INVALID_PARAMS)作为返回值保证本地校验错误与远端错误在 Python 侧呈现一致的数值语义日志辅助错误码的toString()映射types.cpp提供人类可读字符串排查时优先在日志中搜索错误名如TASK_NOT_FOUND而非仅凭数值猜测。快速排查速查表场景可能返回的错误码首要检查项调用SubmitTransfer失败ERR_TOO_MANY_REQUESTS (-2)BatchID分配的请求上限传输地址未注册ERR_ADDRESS_NOT_REGISTERED (-3)registerLocalMemory/registerRemoteMemory调用及元数据同步节点间握手失败ERR_DNS / ERR_SOCKET / ERR_MALFORMED_JSON (-101 ~ -103)主机名解析、端口连通、版本一致性无可用 RDMA 设备ERR_DEVICE_NOT_FOUND (-6)rdma_devices配置与硬件拓扑内存注册地址重叠ERR_ADDRESS_OVERLAPPED (-7)多次注册的地址区间Store 写入失败BUFFER_OVERFLOW (-10)、WRITE_FAIL (-500)空间水位、写入链路对象操作失败OBJECT_NOT_FOUND (-704)、OBJECT_ALREADY_EXISTS (-705)、LEASE_EXPIRED (-707)key 是否存在、租约状态数据一致性告警CHECKSUM_MISMATCH (-801)传输链路、内存完整性异步任务查询失败TASK_NOT_FOUND (-1400)任务是否已被 master 历史裁剪HA 相关失败ETCD_* (-1000 系列)etcd 集群健康状态总结Mooncake 的错误码体系以返回值即错误原因为设计核心TransferEngine 侧按参数/握手/其他三大类组织 17 个核心错误码Store 侧则以负整数区间分段组织 40 个错误码覆盖缓冲区、Segment、对象、传输、RPC、HA、文件、任务、DFS、租户配额等全部操作面。掌握错误码的数值区间规律与各错误码背后的源码触发路径error.h、types.h、types.cpp即可在基于 Mooncake 的 KVCache 传输与分布式存储开发中快速定位问题、缩短排障时间。官方文档全文可继续参阅 error-code.md更多故障场景见 troubleshooting.md。赞分享人工智能大模型模型推理服务后端【免费下载链接】MooncakeMooncake is the serving platform for Kimi, a leading LLM service provided by Moonshot AI.项目地址https://gitcode.com/gh_mirrors/mo/Mooncake点击查看免费下载相关推荐15 分钟从克隆到上线Hugo PaperMod 主题部署 GitHub Pages 完整指南15 分钟从克隆到上线Hugo PaperMod 主题部署 GitHub Pages 完整指南 刚写完几篇 Markdown却找不到一个配得上它们的页面博人工智能大模型模型推理服务后端SeaTunnel 错误码速查手册API / Common / Connector 全量错误码排查指南SeaTunnel 错误码速查手册API / Common / Connector 全量错误码排查指南 本篇指南以 Apache SeaTunnel 官方文档数据工程大数据批处理流处理Flax 错误类体系详解flax.errors 参考指南与报错排查路径Flax 错误类体系详解flax.errors 参考指南与报错排查路径 在 Flax 中几乎所有设计上有明确语义的运行时错误都不是普通的 ValueEr人工智能深度学习机器学习上一篇Slate v2 绝对架构评审实战指南从 state/tx 事务化公共 API 到扩展命名空间硬切下一篇WordPress Gutenberg BlockMover 组件完全指南块移动按钮的 API 设计、无障碍与源码解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考