用途
Opentrons Python API v2 用于通过 Python 协议控制液体处理机器人(OT-2 和 Flex),将人工、易出错的移液流程转化为自动化、可复现的协议。一段约 100 行的协议即可替代数小时的人工操作,实现精确且有记录的液体处理。
适用场景包括:编写自动移液协议;设置梯度稀释、板复制或试剂分配;将温控、磁分离或读板集成到工作流中;将 OT-2 协议适配到 Flex;排查协议执行或硬件集成问题;优化移液参数(流速、吸头位置、混匀)。
不适用场景:非 Opentrons 液体处理器;与实验室自动化无关的通用 Python 代码;需要特定模块的详细指导时应使用对应的子技能。
机器人平台
Opentrons Flex:具备机械臂(gripper)自动移动耗材、96 通道移液、基于坐标的甲板槽位(A1-D3)、更大的工作体积与甲板空间;废料桶需显式加载(API 2.16+);第 4 列槽位为暂存区。
OT-2:数字甲板槽位(1-12)、槽位 12 固定废料桶、1 通道与 8 通道移液器。
两个平台使用相同的 API 语法,仅平台相关参数不同。
协议结构
每个协议遵循以下框架:导入 protocol_api;定义 metadata(协议名、作者、描述、apiLevel);定义 requirements(如 robotType 为 Flex);实现 run 函数,在其中加载耗材、移液器与模块,并按顺序执行命令。协议完全线性执行,建议使用贴近实验室术语的变量名并添加注释。
核心 API 组件
加载设备:通过 load_labware 加载标准或自定义耗材;通过 load_instrument 加载 Flex 或 OT-2 移液器;通过 load_module 加载温控、磁力、热循环等模块;Flex 在 API 2.16+ 需通过 load_trash_bin 加载废料桶。
访问孔位:支持按名称(plate["A1"])、按索引(wells()[0])、按字典(wells_by_name())、按行/列(rows()、columns())以及范围(wells("A1", "H12"))访问。
液体处理命令:pick_up_tip、aspirate、dispense、blow_out、mix、drop_tip/return_tip;复杂操作包括 distribute(单源多目标)、consolidate(多源单目标)、transfer(一对一,可带混匀)。
位置控制:top()、bottom()、center() 可带 z 偏移;move_to 移动;protocol.delay 延时。
吸头管理:可指定吸头架位置拾取,或自动跟踪;tips.reset() 重置跟踪。
液体跟踪:define_liquid 定义试剂,load_liquid 为孔位分配液体与体积。
运行时参数:通过 add_parameters 添加 int、float 等用户可配置变量,在 run 中通过 protocol.params 访问。
硬件模块
温度模块:精确加热/冷却(4-95°C),set_temperature 阻塞至达到温度,deactivate 关闭。
加热振荡模块:温控加轨道混匀,需 close_labware_latch、set_and_wait_for_temperature、set_and_wait_for_shake_speed,结束后 deactivate_shaker、deactivate_heater、open_labware_latch。
热循环模块:PCR 热循环,支持 close_lid、set_lid_temperature、set_block_temperature、execute_profile 执行温度曲线、deactivate_lid/block、open_lid。
吸光度读板器(仅 Flex):微孔板分光光度,支持 initialize 单/多波长、read 导出数据,通过 data[波长]["孔名"] 访问结果。
磁力模块(仅 Flex):磁珠分离,将板移至磁力模块后延时等待分离,再移取上清。
Flex 专属功能
机械臂:move_labware 可在位置间移动耗材、移至模块或废料槽,支持 pick_up_offset 与 drop_offset 偏移;移动前需打开模块盖或锁扣。
96 通道移液:flex_96channel_1000 可一次拾取整盒吸头并整板转移。
暂存区槽位:第 4 列(A4、B4、C4、D4)用于读板器盖存放、临时耗材放置与机械臂操作;存在吸光度读板器时不能在第 4 列加载耗材。
将 OT-2 协议适配到 Flex
需更新 requirements 为 Flex;更换移液器型号(如 p300_single_gen2 改为 flex_1channel_1000);更换吸头架型号;API 2.16+ 加载废料桶;甲板槽位可选用数字或坐标格式(两者均可用)。
常见模式
梯度稀释:从源转移至首个目标,再依次进行带混匀的连续转移。
板复制:整板 wells() 一对一转移,new_tip 设为 always。
挑孔转移:指定源孔与目标孔列表进行转移。
试剂分配:distribute 从储液槽分配到板,可设 disposal_volume 与 new_tip。
最佳实践
使用液体跟踪;添加运行时参数;用 distribute/consolidate 优化吸头消耗;针对黏稠或易挥发液体调整流速;加入延时等待混匀、沉降或温度平衡;协议结束停用模块;先在仿真中验证;充分注释与文档化;必要时加入暂停等待人工干预;校准耗材偏移。
高级功能
条件逻辑:根据参数或孔位是否有液体动态执行。
气隙:aspirate 后 air_gap 防止滴漏。
触壁:touch_tip 去除吸头外壁液滴。
吹出:blow_out 确保完全排液。
常见错误
忘记拾取吸头即吸液会报错;协议结束未停用模块会保持温度;机械臂移动前未打开锁扣或盖子会导致失败。
限制
仅适用于 Opentrons 液体处理器;部分模块(吸光度读板器、磁力模块、机械臂)仅 Flex 支持;Flex 废料桶需 API 2.16+ 显式加载;存在吸光度读板器时第 4 列不可加载耗材。