| 1 | package Peta::NN::Pipeline; | ||
| 2 | # ABSTRACT: models in series, and routed by a classifier | ||
| 3 | |||
| 4 | # Models put together: in series, where each step's answer is the next step's | ||
| 5 | # input (Apfel -> Äpfel -> Äpfeln), and with routing, where a classifying | ||
| 6 | # step's answer decides which model a later step uses. | ||
| 7 | # | ||
| 8 | # The models stay what they are: each does its one limited transformation and | ||
| 9 | # knows nothing of the others, or of what its parameters mean. What a chain | ||
| 10 | # means is written here, in the pipeline's steps, by whoever builds it. | ||
| 11 | # | ||
| 12 | # This is part of the inference leg: it needs Peta::NN::Inference and the | ||
| 13 | # model files, nothing of the training leg. | ||
| 14 | |||
| 15 | use v5.36; | ||
| 16 | |||
| 17 | use Peta::NN::Inference; | ||
| 18 | |||
| 19 | our $VERSION = '0.2610090'; | ||
| 20 | |||
| 21 | my $ANY = '*'; # in a routing table: the model for every answer not listed | ||
| 22 | |||
| 23 | # models { name => model }: a model file's path, or an object that answers | ||
| 24 | # (Peta::NN::Inference, or the training leg's Peta::NN::Model) | ||
| 25 | # steps the steps, in order; each is a table with | ||
| 26 | # model the name of a model, or a routing table | ||
| 27 | # { step => { answer => model name, ... } }: the model is chosen by | ||
| 28 | # the answer of the earlier step called `step`; '*' stands for any | ||
| 29 | # answer not listed | ||
| 30 | # params the step's parameters, each one of | ||
| 31 | # 'text' that value, always | ||
| 32 | # \N the Nth argument of the call (0 is the first) | ||
| 33 | # { answer => step } the answer of the earlier step called `step` | ||
| 34 | # name a name for the step, so that later steps can refer to its answer | ||
| 35 | # classify true if the step only looks: its answer is recorded under its | ||
| 36 | # name, and the string goes on to the next step unchanged | ||
| 37 | # pool true if a classifying step answers once for all strings of a | ||
| 38 | # text together (run_texts): every word is evidence, and the | ||
| 39 | # text gets the one answer they point to | ||
| 40 | sub new ($class, %arg) { | ||
| 41 | my $models = $arg{models} // die "models => { name => model, ... } is required\n"; | ||
| 42 | my $steps = $arg{steps} // die "steps => [ ... ] is required\n"; | ||
| 43 | die "a pipeline needs at least one step\n" if !@$steps; | ||
| 44 | |||
| 45 | my %model = map { | ||
| 46 | my $model = $models->{$_}; | ||
| 47 | $_ => !ref $model ? Peta::NN::Inference->load($model) | ||
| 48 | : $model->can('inference') ? $model->inference | ||
| 49 | : $model | ||
| 50 | } keys %$models; | ||
| 51 | |||
| 52 | my (%named, $arguments); | ||
| 53 | my $self = bless { model => \%model, steps => [] }, $class; | ||
| 54 | for my $n (0 .. $#$steps) { | ||
| 55 | my %step = %{ $steps->[$n] }; | ||
| 56 | my $where = 'step ' . ($n + 1); | ||
| 57 | my $spec = $step{model} // die "$where names no model\n"; | ||
| 58 | |||
| 59 | # Every model a step may use must exist, and a routing step must | ||
| 60 | # route by a step that came before it. | ||
| 61 | my @used = $spec; | ||
| 62 | if (ref $spec eq 'HASH') { | ||
| 63 | my ($by, @more) = keys %$spec; | ||
| 64 | die "$where routes by more than one step\n" if @more; | ||
| 65 | die "$where routes by '$by', which is not an earlier step\n" if !$named{$by}; | ||
| 66 | @used = values %{ $spec->{$by} }; | ||
| 67 | } | ||
| 68 | defined $model{$_} or die "$where uses the model '$_', which the pipeline does not have\n" for @used; | ||
| 69 | |||
| 70 | for my $param (@{ $step{params} // [] }) { | ||
| 71 | if (ref $param eq 'HASH') { | ||
| 72 | my $from = $param->{answer} // die "$where has a parameter that is a table without `answer`\n"; | ||
| 73 | die "$where takes a parameter from '$from', which is not an earlier step\n" if !$named{$from}; | ||
| 74 | } | ||
| 75 | elsif (ref $param eq 'SCALAR') { | ||
| 76 | die "$where has an argument number that is not a whole number\n" if $$param !~ /\A[0-9]+\z/; | ||
| 77 | $arguments = $$param + 1 if $$param + 1 > ($arguments // 0); | ||
| 78 | } | ||
| 79 | elsif (ref $param) { die "$where has a parameter that is neither text, \\N nor { answer => step }\n" } | ||
| 80 | } | ||
| 81 | die "$where only classifies, so it needs a name for its answer\n" if $step{classify} && !defined $step{name}; | ||
| 82 | die "$where pools, which is for a step that classifies\n" if $step{pool} && !$step{classify}; | ||
| 83 | for my $model (grep { $_->can('kind') } @model{@used}) { | ||
| 84 | die "$where pools, which is for class models\n" if $step{pool} && $model->kind ne 'class'; | ||
| 85 | } | ||
| 86 | $named{ $step{name} } = 1 if defined $step{name}; | ||
| 87 | push @{ $self->{steps} }, \%step; | ||
| 88 | } | ||
| 89 | $self->{arguments} = $arguments // 0; | ||
| 90 | return $self; | ||
| 91 | } | ||
| 92 | |||
| 93 | # How many arguments a call takes after the string. | ||
| 94 | sub arguments ($self) { return $self->{arguments} } | ||
| 95 | |||
| 96 | # Run many strings through the steps. Returns one record per string: | ||
| 97 | # { text, confidence, answers => { step name => answer }, trace => [ ... ] } | ||
| 98 | # with a trace entry [model name, parameters, input, output, confidence] per | ||
| 99 | # step. Strings that reach a step with the same model and parameters go | ||
| 100 | # through it in one pass. | ||
| 101 | sub run ($self, $texts, @arguments) { return $self->_run($texts, [ 0 .. $#$texts ], @arguments) } | ||
| 102 | |||
| 103 | # Run many texts, each a list of strings (its words, say). Returns for each | ||
| 104 | # text the records of its strings. What differs from run() is a pooling | ||
| 105 | # step: it answers once per text. | ||
| 106 | sub run_texts ($self, $texts, @arguments) { | ||
| 107 | my @of = map { my $n = $_; ($n) x @{ $texts->[$n] } } 0 .. $#$texts; | ||
| 108 | my $states = $self->_run([ map { @$_ } @$texts ], \@of, @arguments); | ||
| 109 | my @result = map { [] } @$texts; | ||
| 110 | push @{ $result[ $of[$_] ] }, $states->[$_] for 0 .. $#of; | ||
| 111 | return \@result; | ||
| 112 | } | ||
| 113 | |||
| 114 | # $of says for each string which text it belongs to. | ||
| 115 | sub _run ($self, $texts, $of, @arguments) { | ||
| 116 | die sprintf "this pipeline takes %d argument%s after the string, not %d\n", | ||
| 117 | $self->{arguments}, $self->{arguments} == 1 ? '' : 's', scalar @arguments if @arguments != $self->{arguments}; | ||
| 118 | |||
| 119 | my @state = map { { text => $texts->[$_], of => $of->[$_], confidence => 1, answers => {}, trace => [] } } 0 .. $#$texts; | ||
| 120 | for my $step (@{ $self->{steps} }) { | ||
| 121 | my %batch; # "model, parameters" => the states that take this step that way | ||
| 122 | for my $state (@state) { | ||
| 123 | my $spec = $step->{model}; | ||
| 124 | my $name = $spec; | ||
| 125 | if (ref $spec) { | ||
| 126 | my ($by) = keys %$spec; | ||
| 127 | my $answer = $state->{answers}{$by}; | ||
| 128 | $name = $spec->{$by}{$answer} // $spec->{$by}{$ANY} | ||
| 129 | // die "no model for the answer '$answer' of step '$by'\n"; | ||
| 130 | } | ||
| 131 | my @values = map { ref eq 'HASH' ? $state->{answers}{ $_->{answer} } : ref eq 'SCALAR' ? $arguments[$$_] : $_ } | ||
| 132 | @{ $step->{params} // [] }; | ||
| 133 | push @{ $batch{ join "\x{1f}", $name, @values }{states} }, $state; | ||
| 134 | $batch{ join "\x{1f}", $name, @values }{call} //= [ $name, @values ]; | ||
| 135 | } | ||
| 136 | for my $group (values %batch) { | ||
| 137 | my ($name, @values) = @{ $group->{call} }; | ||
| 138 | my @states = @{ $group->{states} }; | ||
| 139 | if ($step->{pool}) { | ||
| 140 | my %text; | ||
| 141 | push @{ $text{ $_->{of} } }, $_ for @states; | ||
| 142 | for my $members (values %text) { | ||
| 143 | my ($answer, $share) = @{ $self->{model}{$name}->pooled_for([ map { $_->{text} } @$members ], @values)->[0] }; | ||
| 144 | for my $state (@$members) { | ||
| 145 | push @{ $state->{trace} }, [ $name, \@values, $state->{text}, $answer, $share ]; | ||
| 146 | $state->{confidence} *= $share; | ||
| 147 | $state->{answers}{ $step->{name} } = $answer; | ||
| 148 | } | ||
| 149 | } | ||
| 150 | next; | ||
| 151 | } | ||
| 152 | my $answers = $self->{model}{$name}->answers([ map { $_->{text} } @states ], @values); | ||
| 153 | for my $n (0 .. $#states) { | ||
| 154 | my ($state, $answer, $confidence) = ($states[$n], @{ $answers->[$n] }); | ||
| 155 | push @{ $state->{trace} }, [ $name, \@values, $state->{text}, $answer, $confidence ]; | ||
| 156 | $state->{confidence} *= $confidence; | ||
| 157 | $state->{answers}{ $step->{name} } = $answer if defined $step->{name}; | ||
| 158 | $state->{text} = $answer if !$step->{classify}; | ||
| 159 | } | ||
| 160 | } | ||
| 161 | } | ||
| 162 | return \@state; | ||
| 163 | } | ||
| 164 | |||
| 165 | # The pipeline's answer for a string; in list context also its confidence, | ||
| 166 | # the product of the steps' confidences: a chain is as sure as all its links | ||
| 167 | # together. | ||
| 168 | sub predict ($self, $text, @arguments) { | ||
| 169 | my ($state) = @{ $self->run([$text], @arguments) }; | ||
| 170 | return wantarray ? @$state{qw(text confidence)} : $state->{text}; | ||
| 171 | } | ||
| 172 | |||
| 173 | # The answers for many strings at once, in their order. | ||
| 174 | sub predict_all ($self, $texts, @arguments) { | ||
| 175 | return map { $_->{text} } @{ $self->run($texts, @arguments) }; | ||
| 176 | } | ||
| 177 | |||
| 178 | # The same steps as one fused model (Peta::NN::Fused): the models as they | ||
| 179 | # are, and what happens here between two steps inside it. Options as for | ||
| 180 | # Peta::NN::Fused->new (engine, meta). Only steps in series fuse. | ||
| 181 | sub fuse ($self, %arg) { | ||
| 182 | require Peta::NN::Fused; | ||
| 183 | return Peta::NN::Fused->new(models => $self->{model}, steps => $self->{steps}, %arg); | ||
| 184 | } | ||
| 185 | |||
| 186 | # What each step did with one string: a list of | ||
| 187 | # [model name, parameters, input, output, confidence]. | ||
| 188 | sub trace ($self, $text, @arguments) { | ||
| 189 | my ($state) = @{ $self->run([$text], @arguments) }; | ||
| 190 | return @{ $state->{trace} }; | ||
| 191 | } | ||
| 192 | |||
| 193 | 1; | ||
| 194 | |||
| 195 | __END__ |