CoreML 범용 추론기 객체 메서드
coreml_model_request_object는 coreml.new_model_request(...) / coreml.session(...)이 반환하는 추론 객체입니다.
준비된 입력 특성을 모델에 전달하고 출력 이름별로 구성한 결과를 반환합니다.
이 객체의 역할은 다음과 같이 명확합니다.
- 추론 제출
- 비동기 결과 읽기
- 모델 입출력 시그니처 조회
- 현재 request의 실행 구성 조회
텍스트 토큰화, 이미지 전처리 또는 비즈니스 후처리는 담당하지 않으며 이러한 작업은 Lua 계층에서 직접 구성해야 합니다.
이 메서드는 20260319 이후 버전에서 사용할 수 있습니다.
추론 메서드
:predict(inputs[, opts])
반환 결과, 오류 정보 = 범용 추론기 객체:predict(입력 매핑 테이블)
또는
제출 여부, 오류 정보 = 범용 추론기 객체:predict(입력 매핑 테이블, {
async = 비동기 여부,
multi_array_output = "table" 또는 "MLMultiArray",
uses_cpu_only = 이번 요청에서 CPU만 사용할지 여부,
})
단일 샘플 모델 추론을 한 번 실행합니다.
inputs는 입력 이름별로 구성된 테이블이어야 합니다.- 동기 모드에서는 결과 테이블을 바로 반환합니다.
- 비동기 모드에서는
true만 반환하며 나중에:is_done()과:results()로 결과를 가져옵니다. multi_array_output은 모델 출력의MLMultiArray를 네이티브 텐서로 유지할지 Lua 테이블로 변환할지 제어합니다.uses_cpu_only는 이번 추론에만 영향을 주며 객체의 기본 구성은 변경하지 않습니다.
:run(inputs[, opts])
run()은 predict()의 별칭이며 동작이 완전히 같습니다.
:predict_batch(batch_inputs[, opts])
배치 결과, 오류 정보 = 범용 추론기 객체:predict_batch({
{ input_ids = ids1 },
{ input_ids = ids2 },
}, {
async = false,
multi_array_output = "MLMultiArray",
})
batch 추론을 실행합니다. iOS 12+가 필요합니다.
batch_inputs는 배열이어야 하며 배열의 각 항목은 입력 이름별로 구성된 입력 테이블입니다.- 동기 모드에서는 batch 결과 배열을 반환하며 각 요소는 단일 샘플 출력 규칙에 따라 구성됩니다.
- 비동기 모드에서는
true를 반환하며 나중에:results()로 가져옵니다. opts필드는predict()와 같습니다.
:run_batch(batch_inputs[, opts])
run_batch()는 predict_batch()의 별칭이며 동작이 완전히 같습니다.
:results([opts])
반환 결과, 오류 정보 = 범용 추론기 객체:results()
또는
반환 결과, 오류 정보 = 범용 추론기 객체:results({
multi_array_output = "table" 또는 "MLMultiArray",
})
가장 최근 비동기 추론의 결과를 읽습니다.
- 가장 최근 비동기 호출이
predict()에서 이루어졌다면 단일 샘플 결과 테이블을 반환합니다. - 가장 최근 비동기 호출이
predict_batch()에서 이루어졌다면 batch 결과 배열을 반환합니다. multi_array_output은 기본적으로 가장 최근 추론 호출의 설정을 따릅니다.- 비동기 작업이 아직 끝나지 않았다면
nil, "not yet"을 반환합니다. - 현재 읽을 수 있는 성공 결과가 없다면
nil, "unknown"을 반환합니다.
:is_done()
완료 여부 = 범용 추론기 객체:is_done()
가장 최근 비동기 추론이 완료되었는지 확인합니다. predict(..., { async = true }) 또는 predict_batch(..., { async = true })를 호출한 뒤에만 의미가 있습니다.
실행 구성 및 메타데이터
:metadata()
메타데이터 = 범용 추론기 객체:metadata()
모델 자체의 metadata를 반환합니다. 디버깅, 범용 래핑 또는 모델 정보 표시에 적합합니다.
:uses_cpu_only()
기본적으로 CPU만 사용하는지 여부 = 범용 추론기 객체:uses_cpu_only()
이 request를 생성할 때 저장한 기본 CPUOnly 구성을 반환합니다.
:compute_units()
연산 장치 설정 = 범용 추론기 객체:compute_units()
이 request에 현재 기록된 compute_units 문자열을 반환합니다.
- **iOS 12+**에서는 생성 시 기록한 소문자 문자열을 반환합니다.
- 일반적인 반환값에는
"all","cpu_only","cpu","cpu_and_gpu","gpu","cpu_and_neural_engine","ane","neural_engine"이 있습니다. - 생성할 때
uses_cpu_only = true를 전달했다면"cpu_only"를 반환합니다. - iOS 11에서는
nil을 반환합니다.
입출력 시그니처 메서드
:input_count() / :output_count()
입력 / 출력 특성 수를 반환합니다.
:input_features() / :output_features()
이름을 인덱스로 사용하는 특성 설명 테이블을 반환합니다.
현재 실제로 반환하는 필드는 비교적 간단합니다.
typeoptional- 특성 유형이
multi_array이면shape과data_type이 추가로 포함됩니다.
:input_info(name_or_index) / :output_info(name_or_index)
입력 / 출력 이름 또는 1-based 순번으로 단일 특성 정보를 읽습니다.
- 반환 필드는
input_features()/output_features()와 거의 같습니다. name이 추가로 포함됩니다.- 순번 접근에는
input_names()/output_names()와 같은 정렬 규칙을 사용합니다.
:input_names() / :output_names()
안정적으로 정렬된 입력 / 출력 이름 목록을 반환합니다.
- 이름은 사전순으로 정렬됩니다.
output_names()의 순서는 동기 추론 반환 결과의 숫자 인덱스 순서와 같습니다.
:class_labels()
모델이 선언한 클래스 레이블을 반환합니다. iOS 14+가 필요합니다.
수명 주기 및 유형 확인
:close()
기반 request 상태를 제거합니다. 닫은 뒤에는 다른 메서드를 더 호출하지 마십시오.
:is_model_request() / :is_session()
객체 수준 유형 확인 인터페이스이며 두 메서드는 같은 의미의 별칭입니다.
설명
predict()/run()의 반환 결과는 항상 테이블입니다.- 결과는 숫자 인덱스와 출력 이름 인덱스를 모두 지원합니다.
predict_batch()/run_batch()는 batch 결과 배열을 반환하며 배열의 각 항목에서도 숫자 인덱스와 출력 이름 인덱스 두 방식으로 접근할 수 있습니다.- 새 범용 추론기에서는
MLMultiArray가 기본적으로 네이티브 텐서 객체로 유지되므로 후처리를 이어가기 더 적합합니다. - 데이터 내용만 확인하거나 기존 스크립트와 호환해야 한다면
multi_array_output = "table"을 명시적으로 전달할 수 있습니다.
결과 접근 예제:
out[1]
out.text_features
batch_out[1].text_features
예제
local req = assert(coreml.new_model_request(XXT_HOME_PATH.."/models/demo.mlmodelc"))
local out = assert(req:predict({
input_ids = ids,
}, {
multi_array_output = "MLMultiArray",
}))
print(out[1])
print(out.text_features)
print(req:output_names())