Xinference 日志系统全指南级别配置、轮转策略、环境变量与目录结构【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inferenceXinference 提供了完整的日志体系覆盖xinference-local、xinference-supervisor、xinference-worker以及独立 Token Router 服务支持命令行与文件双重输出、按大小/按天自动轮转、text/json 两种格式以及细粒度的下载进度日志控制。本文以 logging.rst 为骨架结合仓库源码constants.py、deploy/utils.py、router/logging_config.py深入讲解日志级别、轮转参数、环境变量、日志目录结构及生产环境下的 Token Router 日志落地实践读完即可独立完成本地与分布式部署的日志排障与运维配置。日志级别配置Xinference 通过命令行参数--log-level控制日志级别所有部署入口local、supervisor、worker均支持该选项。命令行使用以本地集群为例使用DEBUG级别启动xinference-local --log-level debug从 cmdline.py 的 Click 定义可以看到--log-level的默认值是INFO可用的级别按输出量从多到少排列为DEBUG INFO WARNING ERROR CRITICAL源码中同时把该级别透传给TRANSFORMERS_VERBOSITY见 cmdline.py 的set_envs(TRANSFORMERS_VERBOSITY, log_level.lower())因此设置的日志级别会同时约束 Xinference 自身与 Transformers 库的日志输出。级别的作用范围设置日志级别后对命令行stderr 控制台输出与日志文件同时生效两者使用统一的级别配置。这一行为由 deploy/utils.py 中的get_config_dict保证无论console_handler、stream_handler还是file_handler都采用同一个log_level同时xinference、uvicorn、transformers、vllm等 logger 也统一应用该级别。日志文件与轮转策略Xinference 支持日志文件的自动轮转log rotation默认配置为maxBytes单个日志文件达到100MB时触发轮转backupCount最多保留30个备份文件。轮转行为由 core/log.py 中统一的create_rotating_handler工厂实现该函数支持三种轮转模式rotation参数模式实现类触发条件备份控制参数dailyTimedRotatingFileHandler标准库每天午夜whenmidnightbackupCountretention_daysdailysizeSafeTimedAndSizeRotatingFileHandler每天午夜 达到max_bytes按天保留retention_days按文件数量封顶backup_countsizeSafeRotatingFileHandler仅按大小maxBytesbackupCountretention_days值得注意的是constants.py 中XINFERENCE_LOG_ROTATION的默认值实际是dailysize即默认同时按天和按大小进行轮转而在get_config_dict中轮转策略、maxBytes、backupCount、retention_days都会通过 dictConfig 传递给对应的 handler见 deploy/utils.py。多进程安全设计生产环境 Supervisor 与 Worker 可能并发写同一日志文件deploy/utils.py 中的SafeRotatingFileHandler为此做了专门加固使用fcntl文件锁序列化doRollover避免多进程同时轮转导致文件错乱shouldRollover入口检查 inode若其他进程已完成轮转则重新打开流大小判断基于os.fstat().st_size而非stream.tell()反映文件真实大小自动创建父目录避免 xoscar 子池进程通过共享内存重建日志配置时因目录缺失抛FileNotFoundError。环境变量全面控制日志行为Xinference 提供一组环境变量精细控制日志行为定义于 constants.py环境变量默认值说明XINFERENCE_LOG_CONSOLEtrue是否输出到控制台。设为false时仅写文件此时 stdout/stderr 被重定向到 loggertqdm 进度条被采样记录XINFERENCE_LOG_FORMATtext日志格式可选text或jsonXINFERENCE_LOG_DOWNLOAD_PROGRESSsampled仅当XINFERENCE_LOG_CONSOLEfalse时生效控制下载进度条的记录粒度XINFERENCE_LOG_ROTATIONdailysize轮转模式daily、dailysize或sizeXINFERENCE_LOG_RETENTION_DAYS30按天轮转时保留的天数XINFERENCE_LOG_MAX_BYTES104857600100MB按大小轮转的单文件上限XINFERENCE_LOG_BACKUP_COUNT300备份文件数量上限dailysize模式XINFERENCE_LOG_DIRXINFERENCE_HOME/logs日志根目录见 constants.pyXINFERENCE_LOG_POLLING_ACCESSfalse是否记录 Web UI 轮询/progress、/replicas和指标抓取的 access 日志下载进度日志的三种模式XINFERENCE_LOG_DOWNLOAD_PROGRESS只在关闭控制台输出时才有意义合法值及行为源码注释见 constants.pysampled默认每个分片在25/50/75/100%处记录一次退出时记录终态full记录 tqdm 的每一帧进度off不记录进度帧只保留开始/出错行。若传入非法值启动时会向 stderr 打印 WARNING 并回退到sampled见 constants.py。该机制由redirect_streams_to_logger上下文管理器与StreamToLogger实现见 deploy/utils.py它在模型加载期间把 stdout/stderr 重定向到xinference.stdout/xinference.stderrlogger从而把 tqdm 进度条写入日志文件。实际使用示例# 关闭控制台输出下载进度按采样点25/50/75/100%记录 XINFERENCE_LOG_CONSOLEfalse XINFERENCE_LOG_DOWNLOAD_PROGRESSsampled xinference-local # 关闭控制台输出记录下载进度的每一帧 XINFERENCE_LOG_CONSOLEfalse XINFERENCE_LOG_DOWNLOAD_PROGRESSfull xinference-local # 关闭控制台输出不记录任何下载进度日志 XINFERENCE_LOG_CONSOLEfalse XINFERENCE_LOG_DOWNLOAD_PROGRESSoff xinference-local需要说明的是deploy/utils.py 的install_stream_redirect函数注释明确警告不要在进程启动时调用全局流重定向否则会破坏 xoscar 子池的创建因此 Xinference 采用redirect_streams_to_logger上下文管理器做作用域内的临时重定向。text 与 json 两种格式XINFERENCE_LOG_FORMATjson时deploy/utils.py 会选择JsonFileFormatter否则使用TextFileFormatter。text 格式的单行日志见AddressFormatter.formatdeploy/utils.py包含时间戳(UTC, 毫秒精度) 级别 logger名 pid:进程号 role:角色 address:地址 node:主机名 消息内容 [keyvalue...]结构化字段如角色、地址等以keyvalue形式追加在行尾异常堆栈单独换行输出。json 格式则把上述字段组织为结构化 JSON便于对接 ELK 等日志采集系统。日志目录结构所有日志默认存储在XINFERENCE_HOME/logs目录下XINFERENCE_HOME可通过环境变量配置参见 using_xinference.rst。每次启动 Xinference 集群时会在日志目录下创建一个以**集群启动时间毫秒时间戳**命名的子目录避免多次启动的日志互相覆盖。本地部署单文件合并本地部署时Supervisor 与 Worker 的日志合并写入同一个文件XINFERENCE_HOME/logs └── local_1699503558105 └── xinference.log其中1699503558105为集群创建时刻的毫秒时间戳。因此多次本地启动集群时可以依据该时间戳定位到对应批次的日志XINFERENCE_DEFAULT_LOG_FILE_NAME为xinference.log见 constants.py。分布式部署按角色分目录分布式部署时Supervisor 与每个 Worker 在日志目录下各自创建子目录子目录名以角色名 该角色启动时间的毫秒时间戳命名XINFERENCE_HOME/logs └── supervisor_1699503558908 └── xinference.log worker_1699503559105 └── xinference.log这种按角色隔离的目录设计让运维人员可以按节点、按角色快速检索日志。注意日志目录本身是全局配置的XINFERENCE_LOG_DIR默认os.path.join(XINFERENCE_HOME, logs)见 constants.py审计日志audit.log也写入同一目录见 api/oauth2/advanced/audit.py。Token Router 日志生产落地实践独立的xinference-router服务复用与 Supervisor/Worker 相同的文件格式器与轮转 handler由 router/logging_config.py 的configure_router_logging调用get_config_dict与get_log_file(router)完成因此具备一致的 text/json 格式与轮转能力。systemd 部署示例文档给出了一份适合生产 systemd 部署的非敏感配置写入/etc/xinference/router.envXINFERENCE_TOKEN_ROUTER_LOG_LEVELINFO XINFERENCE_TOKEN_ROUTER_ACCESS_LOGfalse XINFERENCE_LOG_FORMATjson XINFERENCE_LOG_CONSOLEfalse XINFERENCE_LOG_DIR/data/inference/logs/router XINFERENCE_LOG_ROTATIONdailysize XINFERENCE_LOG_RETENTION_DAYS30 XINFERENCE_LOG_MAX_BYTES104857600 XINFERENCE_LOG_BACKUP_COUNT300应用这些设置后Router 的应用日志写入/data/inference/logs/router/xinference.log。要点该目录必须存在且对 Router 服务账号可写轮转由 Xinference 自身管理不要再对同一文件叠加系统logrotate/copytruncate规则以免双重轮转导致文件错乱XINFERENCE_TOKEN_ROUTER_LOG_LEVEL的合法取值与 Python logging 级别一致CRITICAL/ERROR/WARNING/INFO/DEBUG/NOTSET非法值会被 logging_config.py 的normalize_log_level规整回INFOXINFERENCE_TOKEN_ROUTER_ACCESS_LOG默认false见 logging_config.py。Router 日志内容与安全边界Router 会输出结构化的生命周期、配置、路由决策、完成、拒绝以及后端错误事件。路由事件在可用时会同时记录请求的虚拟模型名与选中的物理后端模型 UID便于在 Token Router 场景下追踪每个请求实际打到哪个后端。出于安全考虑以下内容绝不会出现在 Router 日志中请求体、prompt/消息内容、响应体Authorization头、API Key、控制面 token。URL 也会经过sanitize_log_url见 logging_config.py剥除凭据、查询参数与 fragment 后再记录。结构化字段采用白名单机制只有_ROUTER_LOG_FIELDS中的字段才会被写入见router_log_extralogging_config.py从机制上杜绝敏感字段泄漏。Uvicorn 访问日志与 journal 兜底Uvicorn access 日志默认关闭因为它会重复记录高流量的请求信息仅当需要 access 日志诊断时才设置XINFERENCE_TOKEN_ROUTER_ACCESS_LOGtrue。Uvicorn error 日志保持开启并复用同一套 Xinference 日志配置。在 systemd 部署中应保持 journal 输出开启作为进程生命周期消息与应用日志初始化前发生的启动失败信息的兜底通道——这一阶段应用日志系统尚未就绪只能依赖 journald 留存排障线索。小结关注点推荐做法日常排障xinference-local --log-level debug或在启动命令前设置XINFERENCE_LOG_CONSOLEfalse只写文件长时间运行依赖默认的dailysize轮转100MB 上限 30 天保留或按需调XINFERENCE_LOG_MAX_BYTES/XINFERENCE_LOG_RETENTION_DAYS日志采集设置XINFERENCE_LOG_FORMATjson对接 ELK 等系统下载模型排障XINFERENCE_LOG_CONSOLEfalseXINFERENCE_LOG_DOWNLOAD_PROGRESSfull记录每一帧进度Router 生产部署使用router.env模板目录预创建且仅由 Xinference 轮转避免叠加 logrotateXinference 的日志体系把控制台输出、文件轮转、进度条捕获、结构化格式、安全脱敏整合为一套统一配置既适合单机本地调试也足以支撑分布式集群与独立 Token Router 的生产运维需求。如需进一步了解日志与审计的联动如audit.log与审计中心可继续阅读 audit_security.rst 与 logging.rst 相关章节。【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/16 19:53:34 · 阅读 1.2k Xinference 日志系统全指南：级别配置、轮转策略、环境变量与目录结构
Xinference 日志系统全指南级别配置、轮转策略、环境变量与目录结构【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inferenceXinference 提供了完整的日志体系覆盖xinference-local、xinference-supervisor、xinference-worker以及独立 Token Router 服务支持命令行与文件双重输出、按大小/按天自动轮转、text/json 两种格式以及细粒度的下载进度日志控制。本文以 logging.rst 为骨架结合仓库源码constants.py、deploy/utils.py、router/logging_config.py深入讲解日志级别、轮转参数、环境变量、日志目录结构及生产环境下的 Token Router 日志落地实践读完即可独立完成本地与分布式部署的日志排障与运维配置。日志级别配置Xinference 通过命令行参数--log-level控制日志级别所有部署入口local、supervisor、worker均支持该选项。命令行使用以本地集群为例使用DEBUG级别启动xinference-local --log-level debug从 cmdline.py 的 Click 定义可以看到--log-level的默认值是INFO可用的级别按输出量从多到少排列为DEBUG INFO WARNING ERROR CRITICAL源码中同时把该级别透传给TRANSFORMERS_VERBOSITY见 cmdline.py 的set_envs(TRANSFORMERS_VERBOSITY, log_level.lower())因此设置的日志级别会同时约束 Xinference 自身与 Transformers 库的日志输出。级别的作用范围设置日志级别后对命令行stderr 控制台输出与日志文件同时生效两者使用统一的级别配置。这一行为由 deploy/utils.py 中的get_config_dict保证无论console_handler、stream_handler还是file_handler都采用同一个log_level同时xinference、uvicorn、transformers、vllm等 logger 也统一应用该级别。日志文件与轮转策略Xinference 支持日志文件的自动轮转log rotation默认配置为maxBytes单个日志文件达到100MB时触发轮转backupCount最多保留30个备份文件。轮转行为由 core/log.py 中统一的create_rotating_handler工厂实现该函数支持三种轮转模式rotation参数模式实现类触发条件备份控制参数dailyTimedRotatingFileHandler标准库每天午夜whenmidnightbackupCountretention_daysdailysizeSafeTimedAndSizeRotatingFileHandler每天午夜 达到max_bytes按天保留retention_days按文件数量封顶backup_countsizeSafeRotatingFileHandler仅按大小maxBytesbackupCountretention_days值得注意的是constants.py 中XINFERENCE_LOG_ROTATION的默认值实际是dailysize即默认同时按天和按大小进行轮转而在get_config_dict中轮转策略、maxBytes、backupCount、retention_days都会通过 dictConfig 传递给对应的 handler见 deploy/utils.py。多进程安全设计生产环境 Supervisor 与 Worker 可能并发写同一日志文件deploy/utils.py 中的SafeRotatingFileHandler为此做了专门加固使用fcntl文件锁序列化doRollover避免多进程同时轮转导致文件错乱shouldRollover入口检查 inode若其他进程已完成轮转则重新打开流大小判断基于os.fstat().st_size而非stream.tell()反映文件真实大小自动创建父目录避免 xoscar 子池进程通过共享内存重建日志配置时因目录缺失抛FileNotFoundError。环境变量全面控制日志行为Xinference 提供一组环境变量精细控制日志行为定义于 constants.py环境变量默认值说明XINFERENCE_LOG_CONSOLEtrue是否输出到控制台。设为false时仅写文件此时 stdout/stderr 被重定向到 loggertqdm 进度条被采样记录XINFERENCE_LOG_FORMATtext日志格式可选text或jsonXINFERENCE_LOG_DOWNLOAD_PROGRESSsampled仅当XINFERENCE_LOG_CONSOLEfalse时生效控制下载进度条的记录粒度XINFERENCE_LOG_ROTATIONdailysize轮转模式daily、dailysize或sizeXINFERENCE_LOG_RETENTION_DAYS30按天轮转时保留的天数XINFERENCE_LOG_MAX_BYTES104857600100MB按大小轮转的单文件上限XINFERENCE_LOG_BACKUP_COUNT300备份文件数量上限dailysize模式XINFERENCE_LOG_DIRXINFERENCE_HOME/logs日志根目录见 constants.pyXINFERENCE_LOG_POLLING_ACCESSfalse是否记录 Web UI 轮询/progress、/replicas和指标抓取的 access 日志下载进度日志的三种模式XINFERENCE_LOG_DOWNLOAD_PROGRESS只在关闭控制台输出时才有意义合法值及行为源码注释见 constants.pysampled默认每个分片在25/50/75/100%处记录一次退出时记录终态full记录 tqdm 的每一帧进度off不记录进度帧只保留开始/出错行。若传入非法值启动时会向 stderr 打印 WARNING 并回退到sampled见 constants.py。该机制由redirect_streams_to_logger上下文管理器与StreamToLogger实现见 deploy/utils.py它在模型加载期间把 stdout/stderr 重定向到xinference.stdout/xinference.stderrlogger从而把 tqdm 进度条写入日志文件。实际使用示例# 关闭控制台输出下载进度按采样点25/50/75/100%记录 XINFERENCE_LOG_CONSOLEfalse XINFERENCE_LOG_DOWNLOAD_PROGRESSsampled xinference-local # 关闭控制台输出记录下载进度的每一帧 XINFERENCE_LOG_CONSOLEfalse XINFERENCE_LOG_DOWNLOAD_PROGRESSfull xinference-local # 关闭控制台输出不记录任何下载进度日志 XINFERENCE_LOG_CONSOLEfalse XINFERENCE_LOG_DOWNLOAD_PROGRESSoff xinference-local需要说明的是deploy/utils.py 的install_stream_redirect函数注释明确警告不要在进程启动时调用全局流重定向否则会破坏 xoscar 子池的创建因此 Xinference 采用redirect_streams_to_logger上下文管理器做作用域内的临时重定向。text 与 json 两种格式XINFERENCE_LOG_FORMATjson时deploy/utils.py 会选择JsonFileFormatter否则使用TextFileFormatter。text 格式的单行日志见AddressFormatter.formatdeploy/utils.py包含时间戳(UTC, 毫秒精度) 级别 logger名 pid:进程号 role:角色 address:地址 node:主机名 消息内容 [keyvalue...]结构化字段如角色、地址等以keyvalue形式追加在行尾异常堆栈单独换行输出。json 格式则把上述字段组织为结构化 JSON便于对接 ELK 等日志采集系统。日志目录结构所有日志默认存储在XINFERENCE_HOME/logs目录下XINFERENCE_HOME可通过环境变量配置参见 using_xinference.rst。每次启动 Xinference 集群时会在日志目录下创建一个以**集群启动时间毫秒时间戳**命名的子目录避免多次启动的日志互相覆盖。本地部署单文件合并本地部署时Supervisor 与 Worker 的日志合并写入同一个文件XINFERENCE_HOME/logs └── local_1699503558105 └── xinference.log其中1699503558105为集群创建时刻的毫秒时间戳。因此多次本地启动集群时可以依据该时间戳定位到对应批次的日志XINFERENCE_DEFAULT_LOG_FILE_NAME为xinference.log见 constants.py。分布式部署按角色分目录分布式部署时Supervisor 与每个 Worker 在日志目录下各自创建子目录子目录名以角色名 该角色启动时间的毫秒时间戳命名XINFERENCE_HOME/logs └── supervisor_1699503558908 └── xinference.log worker_1699503559105 └── xinference.log这种按角色隔离的目录设计让运维人员可以按节点、按角色快速检索日志。注意日志目录本身是全局配置的XINFERENCE_LOG_DIR默认os.path.join(XINFERENCE_HOME, logs)见 constants.py审计日志audit.log也写入同一目录见 api/oauth2/advanced/audit.py。Token Router 日志生产落地实践独立的xinference-router服务复用与 Supervisor/Worker 相同的文件格式器与轮转 handler由 router/logging_config.py 的configure_router_logging调用get_config_dict与get_log_file(router)完成因此具备一致的 text/json 格式与轮转能力。systemd 部署示例文档给出了一份适合生产 systemd 部署的非敏感配置写入/etc/xinference/router.envXINFERENCE_TOKEN_ROUTER_LOG_LEVELINFO XINFERENCE_TOKEN_ROUTER_ACCESS_LOGfalse XINFERENCE_LOG_FORMATjson XINFERENCE_LOG_CONSOLEfalse XINFERENCE_LOG_DIR/data/inference/logs/router XINFERENCE_LOG_ROTATIONdailysize XINFERENCE_LOG_RETENTION_DAYS30 XINFERENCE_LOG_MAX_BYTES104857600 XINFERENCE_LOG_BACKUP_COUNT300应用这些设置后Router 的应用日志写入/data/inference/logs/router/xinference.log。要点该目录必须存在且对 Router 服务账号可写轮转由 Xinference 自身管理不要再对同一文件叠加系统logrotate/copytruncate规则以免双重轮转导致文件错乱XINFERENCE_TOKEN_ROUTER_LOG_LEVEL的合法取值与 Python logging 级别一致CRITICAL/ERROR/WARNING/INFO/DEBUG/NOTSET非法值会被 logging_config.py 的normalize_log_level规整回INFOXINFERENCE_TOKEN_ROUTER_ACCESS_LOG默认false见 logging_config.py。Router 日志内容与安全边界Router 会输出结构化的生命周期、配置、路由决策、完成、拒绝以及后端错误事件。路由事件在可用时会同时记录请求的虚拟模型名与选中的物理后端模型 UID便于在 Token Router 场景下追踪每个请求实际打到哪个后端。出于安全考虑以下内容绝不会出现在 Router 日志中请求体、prompt/消息内容、响应体Authorization头、API Key、控制面 token。URL 也会经过sanitize_log_url见 logging_config.py剥除凭据、查询参数与 fragment 后再记录。结构化字段采用白名单机制只有_ROUTER_LOG_FIELDS中的字段才会被写入见router_log_extralogging_config.py从机制上杜绝敏感字段泄漏。Uvicorn 访问日志与 journal 兜底Uvicorn access 日志默认关闭因为它会重复记录高流量的请求信息仅当需要 access 日志诊断时才设置XINFERENCE_TOKEN_ROUTER_ACCESS_LOGtrue。Uvicorn error 日志保持开启并复用同一套 Xinference 日志配置。在 systemd 部署中应保持 journal 输出开启作为进程生命周期消息与应用日志初始化前发生的启动失败信息的兜底通道——这一阶段应用日志系统尚未就绪只能依赖 journald 留存排障线索。小结关注点推荐做法日常排障xinference-local --log-level debug或在启动命令前设置XINFERENCE_LOG_CONSOLEfalse只写文件长时间运行依赖默认的dailysize轮转100MB 上限 30 天保留或按需调XINFERENCE_LOG_MAX_BYTES/XINFERENCE_LOG_RETENTION_DAYS日志采集设置XINFERENCE_LOG_FORMATjson对接 ELK 等系统下载模型排障XINFERENCE_LOG_CONSOLEfalseXINFERENCE_LOG_DOWNLOAD_PROGRESSfull记录每一帧进度Router 生产部署使用router.env模板目录预创建且仅由 Xinference 轮转避免叠加 logrotateXinference 的日志体系把控制台输出、文件轮转、进度条捕获、结构化格式、安全脱敏整合为一套统一配置既适合单机本地调试也足以支撑分布式集群与独立 Token Router 的生产运维需求。如需进一步了解日志与审计的联动如audit.log与审计中心可继续阅读 audit_security.rst 与 logging.rst 相关章节。【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考