TICO是三星开源的Python库，用于将PyTorch模块转换为Circle模型——这是三星ONE项目中的轻量级高效表示格式，专为优化的端侧神经网络推理而设计。

TICO：三星开源的PyTorch到边缘设备模型转换工具\n\n## 项目背景与定位\n\n在边缘AI（Edge AI）时代，将训练好的深度学习模型部署到资源受限的端侧设备（如智能手机、IoT设备、嵌入式系统）已成为一个关键挑战。PyTorch作为最流行的深度学习框架之一，其模型通常需要复杂的转换流程才能在边缘设备上高效运行。\n\nTICO（Torch IR to Circle ONE）正是三星为解决这一问题而推出的开源工具。作为三星ONE（On-device Neural Engine）生态系统的一部分，TICO充当了连接PyTorch生态与三星边缘推理引擎的桥梁，让开发者能够轻松地将PyTorch模型转换为专为边缘优化的高效格式。\n\n## 核心功能与技术架构\n\n### 模型转换流程\n\nTICO的核心功能是将PyTorch模块转换为Circle模型。Circle是三星开发的一种轻量级、高效的神经网络表示格式，专为在ONE运行时上进行优化的端侧推理而设计。转换过程基于PyTorch 2.x引入的torch.export机制，确保了对现代PyTorch模型的良好支持。\n\n基本使用流程非常简洁：\n\npython\nimport tico\nimport torch\n\n# 定义你的PyTorch模型\nclass AddModule(torch.nn.Module):\n def forward(self, x, y):\n return x + y\n\n# 准备模型和示例输入\ntorch_module = AddModule()\nexample_inputs = (torch.ones(4), torch.ones(4))\n\n# 转换为Circle模型\ncircle_model = tico.convert(torch_module.eval(), example_inputs)\ncircle_model.save('add.circle')\n\n\n### 从.pt2文件转换\n\nTICO支持从PyTorch 2.1+导出的.pt2文件进行转换，提供了两种使用方式：\n\nPython API方式：\npython\ncircle_model = tico.convert_from_pt2('model.pt2')\ncircle_model.save('model.circle')\n\n\n命令行工具方式：\nbash\npt2-to-circle -i model.pt2 -o model.circle\n\n\n这种灵活性使TICO能够无缝集成到各种MLOps工作流中。\n\n### 直接在Python中运行Circle模型\n\n一个特别实用的功能是，TICO允许在转换后直接运行Circle模型，而无需额外的部署步骤。这为快速验证和调试提供了极大便利：\n\npython\ncircle_model = tico.convert(torch_module, example_inputs)\nresult = circle_model(*example_inputs) # 返回numpy.ndarray\n\n\n注意，此功能需要安装三星的one-compiler包。\n\n## 量化支持：让模型更轻量\n\n边缘部署的一个核心诉求是模型压缩。TICO内置了统一的量化模块，采用简洁的两步工作流：prepare和convert。\n\n### GPTQ量化示例\n\npython\nfrom tico.quantization import prepare, convert\nfrom tico.quantization.config.gptq import GPTQConfig\n\n# 配置量化策略\nquant_config = GPTQConfig()\n\n# 第一步：准备量化\nprepared_model = prepare(model, quant_config)\n\n# 第二步：校准（使用代表性数据集）\nfor data in calibration_dataset:\n prepared_model(data)\n\n# 第三步：应用量化\nquantized_model = convert(prepared_model, quant_config)\n\n\n这种模块化设计抽象了不同量化算法的实现细节，使开发者能够专注于业务逻辑而非底层优化。\n\n## 高级配置选项\n\nTICO提供了丰富的配置选项，以满足不同的部署需求。\n\n### 因果掩码值处理\n\n对于Transformer类模型（如大语言模型），因果注意力掩码中的负无穷值（-inf）可能对量化不友好。TICO提供了legalize_causal_mask_value选项，可以将-inf转换为-120，虽然会引入轻微的精度损失，但能生成更适合量化的模型：\n\npython\nconfig = tico.CompileConfigV1()\nconfig.legalize_causal_mask_value = True\ncircle_model = tico.convert(torch_module, example_inputs, config=config)\n\n\n### 多版本PyTorch支持\n\nTICO支持多个PyTorch版本（2.5、2.6、2.7、2.8及nightly版本），通过构建参数可以指定目标版本：\n\nbash\n./ccex build --torch_ver 2.6\n\n\n这种灵活性确保了TICO能够跟上PyTorch的快速迭代。\n\n## 开发体验与工程实践\n\n### 便捷的构建系统\n\nTICO使用ccex（Circle Compiler EXecution）作为统一的构建和测试工具，简化了开发工作流：\n\nbash\n# 构建Python包\n./ccex build\n\n# 安装生成的包\n./ccex install\n\n# 从wheel安装（非editable模式）\n./ccex install --dist\n\n\n### 全面的测试支持\n\nTICO的测试系统支持多种粒度的测试：\n\nbash\n# 运行所有单元测试\n./ccex test\n\n# 运行特定子目录的测试（如op/、net/）\n./ccex test -k op\n./ccex test -k net\n\n# 运行特定测试类\n./ccex test -k SimpleAdd\n\n# 查看详细调试日志\nTICO_LOG=4 ./ccex test -k add\n\n# 导出中间图IR为PNG\nTICO_GRAPH_DUMP=1 ./ccex test -k add\n\n\n### 代码质量保证\n\n项目集成了ruff（代码检查）、black（代码格式化）和mypy（类型检查），确保代码质量：\n\nbash\n./ccex configure # 配置测试和格式化环境\n./ccex configure format # 仅配置格式化环境\n./ccex configure test # 仅配置测试环境\n\n\n## 应用场景与生态系统\n\n### 三星设备的AI部署\n\n作为三星官方工具，TICO是部署AI模型到Galaxy系列设备、智能电视、家电等三星生态产品的推荐路径。通过将模型转换为Circle格式，开发者可以充分利用三星NPU（神经网络处理单元）的加速能力。\n\n### 跨平台边缘推理\n\n虽然TICO与三星ONE运行时紧密集成，但Circle格式本身的设计目标是通用性。这意味着转换后的模型可以在支持ONE运行时的各种边缘设备上部署，不仅限于三星硬件。\n\n### 大语言模型（LLM）边缘化\n\n随着端侧大模型（On-device LLM）的兴起，TICO的量化功能变得尤为重要。通过GPTQ等量化技术，可以将数十亿参数的大模型压缩到适合手机运行的规模，同时保持可接受的推理质量。\n\n## 技术局限与注意事项\n\n在使用TICO时，开发者需要注意以下几点：\n\n### torch.export的兼容性\n\nTICO内部使用torch.export进行模型捕获，因此输入的PyTorch模块必须是"可导出"的。某些动态控制流（如数据依赖的条件语句）可能无法被正确捕获。开发者可以参考PyTorch官方文档了解导出限制。\n\n### eval()模式的重要性\n\n转换前必须调用model.eval()，以确保模型处于推理模式。这会禁用dropout等仅在训练时启用的层，并冻结batch normalization的统计量。\n\n### one-compiler的依赖\n\n如果需要在Python中直接运行Circle模型，必须安装one-compiler 1.30.0+。仅进行模型转换则不需要此依赖。\n\n## 与其他工具的对比\n\n在PyTorch到边缘部署的工具链中，TICO的定位相对独特：\n\n| 工具 | 目标格式 | 主要用途 | 所属生态 |\n|------|----------|----------|----------|\n| TICO | Circle | 三星设备部署 | 三星ONE |\n| ONNX | ONNX | 跨框架转换 | 社区标准 |\n| TorchScript | TorchScript | PyTorch生产部署 | Meta |\n| TensorRT | TensorRT | NVIDIA GPU优化 | NVIDIA |\n\nTICO的优势在于对三星硬件的深度优化，以及与ONE运行时的无缝集成。对于目标平台为三星设备的开发者，TICO提供了最直接、最高效的部署路径。\n\n## 未来展望\n\n随着边缘AI的快速发展，TICO有望在以下方向持续演进：\n\n1. 更多量化算法：除了GPTQ，未来可能支持AWQ、SmoothQuant等更先进的量化技术\n2. 动态形状支持：更好地支持输入形状动态的模型\n3. 性能分析工具：集成推理性能分析，帮助开发者识别瓶颈\n4. 云边协同：支持与云端训练流程的无缝对接\n\n## 总结\n\nTICO是三星为边缘AI生态贡献的重要开源工具。它简化了PyTorch模型到边缘设备的部署流程，通过量化支持帮助开发者压缩模型，同时保持了良好的开发体验。\n\n对于希望将AI能力带到三星设备、或探索边缘部署最佳实践的开发者来说，TICO是一个值得深入研究的工具。其开源特性也意味着社区可以参与改进，共同推动边缘AI基础设施的发展。

TICO：三星开源的PyTorch到边缘设备模型转换工具\n\n项目背景与定位\n\n在边缘AI（Edge AI）时代，将训练好的深度学习模型部署到资源受限的端侧设备（如智能手机、IoT设备、嵌入式系统）已成为一个关键挑战。PyTorch作为最流行的深度学习框架之一，其模型通常需要复杂的转换流程才能在边缘设备上高效运行。\n\nTICO（Torch IR to Circle ONE）正是三星为解决这一问题而推出的开源工具。作为三星ONE（On-device Neural Engine）生态系统的一部分，TICO充当了连接PyTorch生态与三星边缘推理引擎的桥梁，让开发者能够轻松地将PyTorch模型转换为专为边缘优化的高效格式。\n\n核心功能与技术架构\n\n模型转换流程\n\nTICO的核心功能是将PyTorch模块转换为Circle模型。Circle是三星开发的一种轻量级、高效的神经网络表示格式，专为在ONE运行时上进行优化的端侧推理而设计。转换过程基于PyTorch 2.x引入的torch.export机制，确保了对现代PyTorch模型的良好支持。\n\n基本使用流程非常简洁：\n\npython\nimport tico\nimport torch\n\n定义你的PyTorch模型\nclass AddModule(torch.nn.Module):\n def forward(self, x, y):\n return x + y\n\n准备模型和示例输入\ntorch_module = AddModule()\nexample_inputs = (torch.ones(4), torch.ones(4))\n\n转换为Circle模型\ncircle_model = tico.convert(torch_module.eval(), example_inputs)\ncircle_model.save('add.circle')\n\n\n从.pt2文件转换\n\nTICO支持从PyTorch 2.1+导出的.pt2文件进行转换，提供了两种使用方式：\n\nPython API方式：\npython\ncircle_model = tico.convert_from_pt2('model.pt2')\ncircle_model.save('model.circle')\n\n\n命令行工具方式：\nbash\npt2-to-circle -i model.pt2 -o model.circle\n\n\n这种灵活性使TICO能够无缝集成到各种MLOps工作流中。\n\n直接在Python中运行Circle模型\n\n一个特别实用的功能是，TICO允许在转换后直接运行Circle模型，而无需额外的部署步骤。这为快速验证和调试提供了极大便利：\n\npython\ncircle_model = tico.convert(torch_module, example_inputs)\nresult = circle_model(*example_inputs) 返回numpy.ndarray\n\n\n注意，此功能需要安装三星的one-compiler包。\n\n量化支持：让模型更轻量\n\n边缘部署的一个核心诉求是模型压缩。TICO内置了统一的量化模块，采用简洁的两步工作流：prepare和convert。\n\nGPTQ量化示例\n\npython\nfrom tico.quantization import prepare, convert\nfrom tico.quantization.config.gptq import GPTQConfig\n\n配置量化策略\nquant_config = GPTQConfig()\n\n第一步：准备量化\nprepared_model = prepare(model, quant_config)\n\n第二步：校准（使用代表性数据集）\nfor data in calibration_dataset:\n prepared_model(data)\n\n第三步：应用量化\nquantized_model = convert(prepared_model, quant_config)\n\n\n这种模块化设计抽象了不同量化算法的实现细节，使开发者能够专注于业务逻辑而非底层优化。\n\n高级配置选项\n\nTICO提供了丰富的配置选项，以满足不同的部署需求。\n\n因果掩码值处理\n\n对于Transformer类模型（如大语言模型），因果注意力掩码中的负无穷值（-inf）可能对量化不友好。TICO提供了legalize_causal_mask_value选项，可以将-inf转换为-120，虽然会引入轻微的精度损失，但能生成更适合量化的模型：\n\npython\nconfig = tico.CompileConfigV1()\nconfig.legalize_causal_mask_value = True\ncircle_model = tico.convert(torch_module, example_inputs, config=config)\n\n\n多版本PyTorch支持\n\nTICO支持多个PyTorch版本（2.5、2.6、2.7、2.8及nightly版本），通过构建参数可以指定目标版本：\n\nbash\n./ccex build --torch_ver 2.6\n\n\n这种灵活性确保了TICO能够跟上PyTorch的快速迭代。\n\n开发体验与工程实践\n\n便捷的构建系统\n\nTICO使用ccex（Circle Compiler EXecution）作为统一的构建和测试工具，简化了开发工作流：\n\nbash\n构建Python包\n./ccex build\n\n安装生成的包\n./ccex install\n\n从wheel安装（非editable模式）\n./ccex install --dist\n\n\n全面的测试支持\n\nTICO的测试系统支持多种粒度的测试：\n\nbash\n运行所有单元测试\n./ccex test\n\n运行特定子目录的测试（如op/、net/）\n./ccex test -k op\n./ccex test -k net\n\n运行特定测试类\n./ccex test -k SimpleAdd\n\n查看详细调试日志\nTICO_LOG=4 ./ccex test -k add\n\n导出中间图IR为PNG\nTICO_GRAPH_DUMP=1 ./ccex test -k add\n\n\n代码质量保证\n\n项目集成了ruff（代码检查）、black（代码格式化）和mypy（类型检查），确保代码质量：\n\nbash\n./ccex configure 配置测试和格式化环境\n./ccex configure format 仅配置格式化环境\n./ccex configure test 仅配置测试环境\n\n\n应用场景与生态系统\n\n三星设备的AI部署\n\n作为三星官方工具，TICO是部署AI模型到Galaxy系列设备、智能电视、家电等三星生态产品的推荐路径。通过将模型转换为Circle格式，开发者可以充分利用三星NPU（神经网络处理单元）的加速能力。\n\n跨平台边缘推理\n\n虽然TICO与三星ONE运行时紧密集成，但Circle格式本身的设计目标是通用性。这意味着转换后的模型可以在支持ONE运行时的各种边缘设备上部署，不仅限于三星硬件。\n\n大语言模型（LLM）边缘化\n\n随着端侧大模型（On-device LLM）的兴起，TICO的量化功能变得尤为重要。通过GPTQ等量化技术，可以将数十亿参数的大模型压缩到适合手机运行的规模，同时保持可接受的推理质量。\n\n技术局限与注意事项\n\n在使用TICO时，开发者需要注意以下几点：\n\ntorch.export的兼容性\n\nTICO内部使用torch.export进行模型捕获，因此输入的PyTorch模块必须是"可导出"的。某些动态控制流（如数据依赖的条件语句）可能无法被正确捕获。开发者可以参考PyTorch官方文档了解导出限制。\n\neval()模式的重要性\n\n转换前必须调用model.eval()，以确保模型处于推理模式。这会禁用dropout等仅在训练时启用的层，并冻结batch normalization的统计量。\n\none-compiler的依赖\n\n如果需要在Python中直接运行Circle模型，必须安装one-compiler 1.30.0+。仅进行模型转换则不需要此依赖。\n\n与其他工具的对比\n\n在PyTorch到边缘部署的工具链中，TICO的定位相对独特：\n\n| 工具 | 目标格式 | 主要用途 | 所属生态 |\n|------|----------|----------|----------|\n| TICO | Circle | 三星设备部署 | 三星ONE |\n| ONNX | ONNX | 跨框架转换 | 社区标准 |\n| TorchScript | TorchScript | PyTorch生产部署 | Meta |\n| TensorRT | TensorRT | NVIDIA GPU优化 | NVIDIA |\n\nTICO的优势在于对三星硬件的深度优化，以及与ONE运行时的无缝集成。对于目标平台为三星设备的开发者，TICO提供了最直接、最高效的部署路径。\n\n未来展望\n\n随着边缘AI的快速发展，TICO有望在以下方向持续演进：\n\n1. 更多量化算法：除了GPTQ，未来可能支持AWQ、SmoothQuant等更先进的量化技术\n2. 动态形状支持：更好地支持输入形状动态的模型\n3. 性能分析工具：集成推理性能分析，帮助开发者识别瓶颈\n4. 云边协同：支持与云端训练流程的无缝对接\n\n总结\n\nTICO是三星为边缘AI生态贡献的重要开源工具。它简化了PyTorch模型到边缘设备的部署流程，通过量化支持帮助开发者压缩模型，同时保持了良好的开发体验。\n\n对于希望将AI能力带到三星设备、或探索边缘部署最佳实践的开发者来说，TICO是一个值得深入研究的工具。其开源特性也意味着社区可以参与改进，共同推动边缘AI基础设施的发展。