Chuyển tới nội dung chính

Mô-đun Session của ONNX Runtime

Mô-đun này có sẵn trong các phiên bản phát hành sau phiên bản 20260402

Các đối tượng Session quản lý việc tải mô hình, kiểm tra đầu vào/đầu ra và thực thi suy diễn.

Cấu hình runtime​

onnxruntime.configure(opts)​

assert(onnxruntime.configure({
    log_severity_level = 2,
    log_id = "my-runtime",
    use_global_thread_pools = false,
    global_intra_op_num_threads = 0,
    global_inter_op_num_threads = 0,
}))

Ghi chú:

  • Phải được gọi trước khi tạo bất kỳ đối tượng Session nào
  • Gọi lại sau khi đã có một đối tượng Session hoạt động sẽ trả về lỗi

Các trường được hỗ trợ:

  • log_severity_level
  • log_id
  • use_global_thread_pools
  • global_intra_op_num_threads
  • global_inter_op_num_threads

Tạo đối tượng Session​

onnxruntime.session(model_path[, opts])​

session, err = onnxruntime.session(model_path, opts)

Tải một mô hình ONNX từ đường dẫn tệp.

onnxruntime.session_from_bytes(model_bytes[, opts])​

session, err = onnxruntime.session_from_bytes(model_bytes, opts)

Tạo một đối tượng Session từ các byte mô hình lưu trữ trong bộ nhớ.

Các tùy chọn của Session​

Các trường chung​

  • providers hoặc provider Nhận một chuỗi hoặc mảng chuỗi; các chuỗi cung cấp hiện tại được xử lý là "cpu" và "coreml", và các tên gọi như CPUExecutionProvider và CoreMLExecutionProvider cũng được chấp nhận
  • fallback_to_cpu Boolean, mặc định true
  • intra_op_num_threads
  • inter_op_num_threads
  • log_id
  • session_log_severity_level
  • session_log_verbosity_level
  • optimized_model_path
  • profile_file_prefix
  • free_dimension_overrides
  • config_entries
  • graph_optimization_level Một trong "disable", "basic", "extended", hoặc "all"
  • execution_mode Một trong "sequential" hoặc "parallel"
  • deterministic_compute
  • disable_per_session_threads
  • enable_cpu_mem_arena
  • enable_mem_pattern
  • custom_op_libraries

Ghi chú bổ sung:

  • free_dimension_overrides phải là một bảng mảng, và mỗi mục phải có dạng { by = "name"|"denotation", key = "...", value = integer }
  • config_entries phải là một bảng chuỗi-to-chuỗi
  • custom_op_libraries có thể là một chuỗi đường dẫn đơn, một mảng đường dẫn, hoặc các tay cầm trả về bởi load_custom_op_library(); các mảng có thể kết hợp đường dẫn và tay cầm
  • Nếu providers bị bỏ qua hoặc danh sách cung cấp trống, bản hiện tại sẽ thêm cung cấp CPU mặc định
  • Khi "coreml" có mặt và fallback_to_cpu = true, việc tạo đối tượng Session có thể chuyển xuống CPU nếu quá trình khởi tạo cung cấp CoreML thất bại
  • Nếu bạn truyền providers = {"coreml", "cpu"} một cách rõ ràng, thứ tự đó có nghĩa là CoreML trước, CPU sau

Các trường dành cho nhà cung cấp CoreML​

Khi "coreml" được bao gồm trong providers, các trường sau cũng được hỗ trợ:

  • coreml_compute_units Ưu tiên "all", "cpu_only", "cpu_and_gpu", hoặc "cpu_and_neural_engine"; parser cũng chấp nhận các tên gọi như CPUOnly, CPUAndGPU, CPUAndNeuralEngine, và MLComputeUnits...
  • coreml_create_mlprogram
  • coreml_require_static_input_shapes
  • coreml_enable_on_subgraph
  • coreml_flags
  • coreml_use_cpu_only
  • coreml_use_cpu_and_gpu
  • coreml_only_enable_device_with_ane

Ghi chú bổ sung:

  • coreml_flags, coreml_use_cpu_only, coreml_use_cpu_and_gpu, và coreml_only_enable_device_with_ane là các trường tương thích cũ
  • Các trường mới và cũ có thể được kết hợp, nhưng việc tạo đối tượng Session sẽ thất bại ngay lập tức nếu chúng biểu đạt ý nghĩa mâu thuẫn
  • coreml_only_enable_device_with_ane không thể được kết hợp với các thiết lập tương tác như coreml_compute_units = "cpu_only" hoặc "cpu_and_gpu"

Các phương thức của đối tượng Session​

Kiểm tra cơ bản​

  • session:input_names()
  • session:output_names()
  • session:overridable_initializer_names()
  • session:input_count()
  • session:output_count()
  • session:overridable_initializer_count()

Thông tin loại​

  • session:input_info(name_or_index)
  • session:output_info(name_or_index)
  • session:overridable_initializer_info(name_or_index)

Bảng trả về có thể chứa:

  • name
  • onnx_type
  • is_sparse
  • data_type
  • type
  • has_shape
  • shape
  • symbolic_shape
  • element
  • key_type
  • value

Ghi chú:

  • Các mục tensor / tensor rải rác bao gồm data_type, shape, và symbolic_shape
  • Các mục chuỗi / tùy chọn bao gồm element lồng ghép
  • Các mục map bao gồm key_type và value lồng ghép

Thông tin bộ nhớ​

  • session:memory_info_for_inputs()
  • session:memory_info_for_outputs()

Kết quả hỗ trợ cả truy cập theo thứ tự số và theo tên. Các mục riêng lẻ thường chứa:

  • name
  • id
  • mem_type
  • allocator_type
  • device_type
  • device_mem_type
  • vendor_id

Thẻ và vòng đời​

  • session:metadata()
  • session:close()
  • session:end_profiling()
  • session:profiling_start_time_ns()
  • session:set_ep_dynamic_options(opts)
  • session:register_custom_op_library(path_or_handle)

Ghi chú:

  • end_profiling() trả về đường dẫn tệp đầu ra phân tích
  • set_ep_dynamic_options() chuyển đổi tất cả các khóa và giá trị thành chuỗi trước khi truyền cho ORT
  • register_custom_op_library() xây dựng lại đối tượng Session nền bằng các tùy chọn hiện tại của đối tượng Session cùng với thư viện mới
  • path_or_handle có thể là một đường dẫn tệp hoặc một tay cầm trả về bởi load_custom_op_library()

Thực thi suy diễn​

session:run(inputs[, output_names[, run_options]])​

outputs, err = session:run({
    input_ids = input_tensor,
    attention_mask = mask_tensor,
}, {
    "logits",
}, run_options)

session:run_into(inputs, outputs[, run_options])​

outputs, err = session:run_into({
    x = input_tensor,
}, {
    y = reused_output_tensor,
}, run_options)

session:run_with_iobinding(binding[, run_options])​

outputs, err = session:run_with_iobinding(binding, run_options)

Quy tắc đầu vào:

  • inputs có thể là một mảng vị trí hoặc một bảng được định danh bằng tên đầu vào
  • Các mảng vị trí tuân theo thứ tự đầu vào của mô hình và có thể tiếp tục với các khởi tạo có thể thay đổi
  • Các khóa bảng phải khớp với tên đầu vào hoặc tên khởi tạo có thể thay đổi
  • Các đầu vào tùy chọn có thể bị bỏ qua, hoặc được truyền dưới dạng onnxruntime.optional(nil, type_info)

Quy tắc đầu ra:

  • Giá trị trả về là một bảng
  • Mỗi đầu ra có thể được truy cập cả bằng chỉ số số và bằng tên đầu ra
  • Nếu run_into() tái sử dụng một tensor đầu ra hiện có, bảng trả về chứa cùng một đối tượng

Các tùy chọn chạy​

onnxruntime.run_options([opts])​

local run_options = assert(onnxruntime.run_options({
    tag = "session-run",
    log_severity_level = 2,
    log_verbosity_level = 1,
}))

Các trường được hỗ trợ:

  • tag
  • log_severity_level
  • log_verbosity_level

Các phương thức đối tượng:

  • run_options:tag([value])
  • run_options:log_severity_level([value])
  • run_options:log_verbosity_level([value])
  • run_options:terminate()
  • run_options:reset_terminate()

IOBinding​

session:create_io_binding()​

binding, err = session:create_io_binding()

binding:bind_input(name, value)​

Kết nối một giá trị đầu vào. Các tùy chọn rỗng không được chấp nhận ở đây.

binding:bind_output(name[, spec_or_tensor])​

Hỗ trợ ba dạng:

  • binding:bind_output("y") Kết nối đến bộ nhớ CPU và lấy nó sau đó bằng get_outputs()
  • binding:bind_output("y", existing_tensor) Ghi trực tiếp vào một tensor hiện có
  • binding:bind_output("y", {type = "float32", shape = {1, 2}}) Tạo và trả về một tensor đầu ra mới thông qua API

Nó cũng hỗ trợ:

  • binding:bind_output("y", {mode = "device"})

Các phương thức khác​

  • binding:clear_inputs()
  • binding:clear_outputs()
  • binding:synchronize_inputs()
  • binding:synchronize_outputs()
  • binding:get_outputs()

Ví dụ​

local ort = require("onnxruntime")

local session = assert(ort.session(XXT_HOME_PATH.."/models/demo/model.onnx", {
    providers = {"coreml", "cpu"},
    fallback_to_cpu = true,
    coreml_compute_units = "all",
}))

local x = assert(ort.tensor("float32", {1, 2}, {1.0, 2.0}))
local bias = assert(ort.tensor("float32", {1, 2}, {0.5, -0.5}))
local run_options = assert(ort.run_options({tag = "demo"}))

local outputs = assert(session:run({
    x = x,
    bias = bias,
}, {"y"}, run_options))

print(outputs.y:to_table()[1])