Habilidade de Codificação KPP

Modelos de Energia KPP e Amostragem

Responsável pela integração de modelos PyTorch com o amostrador Kaiwu. Os parâmetros do modelo, a função objetivo e o otimizador permanecem no PyTorch; através do amostrador compatível, conecte o resolvedor Kaiwu ou o fluxo de amostragem existente da tarefa. Não converta automaticamente tarefas comuns de aprendizado de máquina em tarefas de modelo de energia.

Seleção de Componentes

Primeiro, selecione a estrutura com base na entrada, saída e nas relações que precisam ser modeladas, explicando como o componente escolhido atende aos requisitos da tarefa. Quando o usuário especifica a estrutura, siga-a; ao selecionar por conta própria, julgue se a tarefa precisa de relações diretas entre variáveis observadas, fatores ocultos, representação hierárquica, reconstrução de variáveis latentes, geração contextual ou seleção de características e, em seguida, escolha o componente correspondente. O tamanho do modelo não é uma prioridade padrão; primeiro verifique se a capacidade e o efeito correspondem e, em seguida, compare os custos de treinamento e amostragem entre as soluções que atendem aos requisitos.

Capacidade necessária para o problema	Componente	Base de correspondência
Explicar padrões observados com fatores ocultos, ou aprender estrutura bipartida visível/oculta	RestrictedBoltzmannMachine	A representação oculta participa da distribuição de aprendizado necessária para a tarefa; ter apenas entrada binária não é suficiente para decidir usar RBM
Modelar diretamente interações par a par de nós binários, ou amostrar fixando alguns nós	BoltzmannMachine	Nós e suas interações correspondem às variáveis do problema; use métricas da tarefa para verificar se é suficiente para expressar as relações necessárias
Aprender características hierárquicas através de múltiplas camadas de RBM	UnsupervisedDBN	A tarefa precisa de representações aprendidas camada por camada, ou o usuário explicitamente solicita uma pilha de RBMs
Codificar, reconstruir e ter um prior de modelo de energia amostrável para variáveis latentes	QVAE	Tanto a reconstrução quanto o prior de variáveis latentes servem à tarefa; autoencoders comuns não devem ser convertidos em QVAE por isso
Geração de candidatos discretos dependentes de contexto guiada por energia	QDiffusion	O proposal fornece o contexto necessário, e a energia guia os candidatos relevantes para a tarefa
Selecionar subconjuntos de características da entrada de um modelo PyTorch existente	FeatureSelectionWrapper	A tarefa precisa de seleção de características de entrada, usando máscaras 0/1 atualizadas periodicamente

Dados binários, número de rótulos ou a ordem de aparição dos exemplos não podem, por si só, determinar a seleção. Verifique a seleção com os resultados exigidos pela tarefa, como associação, reconstrução, conclusão ou previsão; apenas importar com sucesso ou ter a forma de saída correta não significa correspondência. Quando a tarefa requer relações de ordem superior ou contexto, não se pode considerar o modelo suficiente apenas com base em estatísticas de pares satisfatórias. As diferentes estruturas de treinamento de BM e RBM podem ser encontradas em Paradigmas de Modelo; leia apenas a parte relevante para a tarefa atual.

Estes são diferentes componentes do mesmo pacote KPP, não sendo necessário instalar seis plugins separadamente. Embora a seleção de características resolva um QUBO internamente, ela serve ao treinamento do modelo PyTorch e pertence a esta habilidade; tarefas puras de localização, escalonamento, Max-Cut, etc., que não dependem de um modelo e buscam diretamente a decisão ótima, usam a habilidade Kaiwu SDK. Se a mesma tarefa contiver otimização combinatória e treinamento de energia, ambas as habilidades podem ser carregadas separadamente usando seus respectivos interpretadores.

Ciclo Mínimo de Aplicação da Tarefa

1. Use dados representativos para verificar o efeito da estrutura selecionada na tarefa e registre a escala e o tempo reais de treinamento e geração, planejando a execução formal de acordo. Reserve tempo no orçamento total para salvar o modelo, carregar em novo processo, gerar e verificar relatórios.
2. Complete a entrada completa exigida pelo problema o mais rápido possível. Após cada verificação, salve o modelo, configuração e relatório com o melhor efeito e reutilizáveis; Experimentos subsequentes usam novos diretórios de saída, e o diretório de entrega sempre mantém uma versão executável.
3. Geração em lote acumula por linhas reais: ao adicionar um lote, acumule as linhas desse lote, truncando quando atingir a quantidade solicitada. Use uma solicitação pequena primeiro para verificar quantidade, largura e valores; o número de lotes não é igual ao número de amostras.
4. Verifique separadamente a cópia direta de registros originais, a coincidência natural da amostragem do modelo e a filtragem manual. Combinações comuns podem coincidir em gerações independentes; Filtrar registros coincidentes ou forçar a exclusividade altera a distribuição; se usado, reavalie proporções e associações, etc.
5. Valide de acordo com os requisitos de negócio divulgados da tarefa. Após salvar o modelo, gere novamente em um novo processo usando apenas o modelo entregue e a entrada da solicitação, relatando a qualidade e o tempo da mesma execução. Se o objetivo for alcançado, conclua a entrega; caso contrário, mantenha os resultados atuais e explique honestamente, continuando a tentar com o orçamento restante, desde que a verificação acima seja possível.

Verificação, Instalação Automática, Validação

1. Reutilize o interpretador especificado pelo usuário/existente no projeto e verifique as versões de Python, kaiwu-torch-plugin, kaiwu e torch. Execute python -m pip check uma vez no mesmo ambiente e, em seguida, execute o modo --imports-only de scripts/verify_kpp.py no diretório da habilidade. Se o resultado da verificação já existir desta execução, reutilize-o e prossiga para a tarefa sem escanear o ambiente ou testar treinamento genérico.
2. Só verifique o plano de instalação e instale se faltar um pacote; se houver conflitos de dependência, pacotes offline, problemas de versão do Python ou suporte a wheel, siga as Instruções de Instalação e escolha um ambiente compatível com base nos metadados reais.
3. Reutilize o amostrador compatível fornecido pela tarefa. Só verifique a licença correspondente ao selecionar SDK SA/CIM, não trate a falta de licença do SDK como se todos os amostradores locais não pudessem treinar. A inicialização da licença e as restrições não interativas estão nas instruções de instalação.
4. Use o programa real da tarefa para validar o modelo selecionado; só execute o modo padrão do script de verificação se não houver programa de tarefa e for necessário verificar o treinamento com amostragem do SDK. KPP_IMPORT_OK prova apenas a importação; KPP_TRAIN_OK prova apenas o treinamento em pequena escala coberto pelo script.

Logs de verificação, arquivos temporários e cópias de validação permanecem no diretório da tarefa. CIM em nuvem só deve ser usado quando a tarefa explicitamente precisar e houver cota/licença. Ao chamar o Kaiwu CIM, task_name deve começar com kpp-skill, para facilitar as estatísticas do backend; por exemplo, kpp-skill-rbm-train. Se o nome da tarefa existente não tiver esse prefixo, adicione kpp-skill- na frente.

Contrato de Treinamento e Geração

Caminhos de importação públicos para BM e RBM:

from kaiwu.torch_plugin import BoltzmannMachine, RestrictedBoltzmannMachine

Ao selecionar SDK SA, SimulatedAnnealingOptimizer é importado de kaiwu.classical. A construção de BM usa BoltzmannMachine(num_nodes, quadratic_coef=None, linear_bias=None, device=None); RBM usa RestrictedBoltzmannMachine(num_visible, num_hidden, quadratic_coef=None, linear_bias=None, device=None). Taxa de aprendizado, decaimento de peso, etc., são definidos no otimizador PyTorch, não passe learning_rate, k, batch_size ou outros parâmetros de treinamento para o construtor do modelo.

• RBM: get_hidden(batch, bernoulli=True) e sample(sampler) retornam o estado conjunto visível+oculto, a largura é num_visible + num_hidden. O número de linhas do lote positivo e do pool de amostras negativo pode ser diferente; calcule a média separadamente; não force o mesmo número de amostras. objective(positive, negative) retorna um escalar. Escreva diretamente positive = model.get_hidden(batch, bernoulli=True), não desempacote o valor de retorno nem concatene a camada visível. O padrão de get_hidden é bernoulli=False, e a parte oculta são probabilidades; para expectativas positivas legais do RBM, só é necessário bernoulli=True ao entregar amostras binárias conjuntas. Não trate estados de probabilidade como amostras binárias já amostradas. A capacidade do pool é configurada conforme o amostrador real; para SDK SA, use SimulatedAnnealingOptimizer(size_limit=...); não invente set_config nem adicione parâmetros num_solutions indefinidos a sample.
• Amostragem SDK: sampler.solve retorna uma matriz ±1 bidimensional com spins de referência anexados no final. Internamente, o sample do KPP normaliza os spins de referência, remove a coluna final e converte para tensor float 0/1. Não remova colunas ou converta novamente o valor de retorno de sample. Quando o usuário fornece soluções de teste fixas, cada solve retorna o conjunto inteiro de soluções inalterado; não atribua soluções diferentes a condições diferentes, nem repita a primeira linha para completar o número de amostras. A amostragem condicional deve verificar simultaneamente as colunas fixas e as colunas livres convertidas de cada solução, não apenas a forma.
• Ordem de treinamento: Cada passo: optimizer.zero_grad() → fase positiva/negativa → objective → backward() → step(); objective e backward() não podem estar dentro de torch.no_grad(). sample() retorna um tensor de amostra sem gradiente, o gradiente vem do recálculo da energia em objective; se sample() está dentro ou fora de no_grad não afeta o treinamento. Mantenha o modelo, os dados e os tensores manuais no mesmo device. Verifique a largura das fases positiva/negativa, a natureza binária da fase negativa, a perda/gradiente finitos e a atualização real dos parâmetros.
• BM / DBN: Amostragem condicional usa condition_sample(sampler, s_visible), que sempre fixa os primeiros s_visible.shape[1] nós, chamando o resolvedor uma vez para cada linha de condição. Quando as posições conhecidas diferem por linha, reorganize linha por linha: permute linear_bias e o quadratic_coef simetrizado colocando as posições conhecidas na frente, construa um BoltzmannMachine temporário com os parâmetros permutados, chame condition_sample e depois reverta a permutação das colunas para a ordem original. Antes de usar DBN, chame create_rbm_layer(input_dim); após o treinamento, chame mark_as_trained() antes de forward/transform.
• QVAE: Pode injetar encoder/decoder/bm/sampler no construtor, ou subclassificar para implementar quatro fábricas _create_*. config contém num_latent_units / loss_type / dist_beta / kl_beta / weight_decay. A correção da média Bernoulli é uma configuração opcional; quando usada, chame set_dataset_mean e set_train_bias separadamente após a construção, não assuma que definir a média posteriormente atualiza automaticamente o viés. A média pode ser um escalar ou um tensor por dimensão, conforme a interface atual. encoder+decoder e BM usam dois otimizadores, a atualização do BM usa bm_loss(q.detach(), weight_decay); veja Paradigmas de Modelo. A avaliação final mantém a correção da média de entrada e o viés de saída do treinamento. q são os logits do encoder, (q > 0).float() é uma decisão hard, não a média posterior. A diferença entre reconstrução nativa e média está no parágrafo QVAE da documentação de referência. Reconstrução aleatória ou decodificação da média posterior real são aceitáveis; calcule e salve as métricas dos logits finais reais, explicando o método usado, não trate a qualidade de um pequeno treinamento como condição de aprovação da interface.
• QDiffusion: proposal entrada [B,L], saída [B,L,V] logits. Quando a tarefa requer conclusão de contexto, use estruturas como self-attention para que posições ausentes leiam outras posições; embedding posicional + MLP só pode aprender preferências posicionais, mesmo com alta taxa de acerto, não satisfaz a conclusão de contexto. EnergyModel subclasses implementam score_conditioned(noisy, candidate, attention_mask) retornando [B,1]. SequenceTokenSpec é importado de kaiwu.torch_plugin.qdiffusion, não exportado no nível superior. Quando apenas "tamanho do vocabulário V" é fornecido, mantenha a largura de saída V; ids especiais devem estar dentro desse vocabulário e ser separados dos tokens de conteúdo. Não interprete V como vocabulário de conteúdo e expanda para V+4. Quando os ids de conteúdo preenchem V ou o mapeamento de ids especiais não está claro, liste os mapeamentos a serem confirmados na solução; antes da confirmação, não use largura de saída expandida nem reduza as categorias de conteúdo existentes do usuário. Ao treinar o proposal do zero, primeiro complete o treinamento de conclusão independente, depois congele e treine a energia; o objective nativo corta o gradiente do proposal internamente, não pode ser usado para pré-treiná-lo. Treine com generator.objective({"targets": batch}), gere com generator.generate(init, max_steps=...). Quando freeze_proposal=True, apenas o lado da energia é otimizado. Condições de integração completas em Paradigmas de Modelo.
• Seleção de Características (MAIFS): from kaiwu.torch_plugin import FeatureSelectionWrapper, QuadraticLinearSolver. Assinatura do construtor: FeatureSelectionWrapper(model, feature_dim, lambda_reg=0.0, cardinality_k=None, min_selected_features=None, max_selected_features=None, solver="local_search", mask_update_epochs=None, input_feature_axis=-1, solver_kwargs=None). Treine com sel.fit_weights(loader, loss_fn, optimizer, train_epochs): loader produz (x, y), loss_fn retorna um escalar, optimizer age sobre sel.model.parameters(). A máscara é atualizada a cada mask_update_epochs épocas; quando None, só é atualizada ao chamar manualmente update_mask(loader, loss_fn, hessian_mode="full"|"diagonal", max_samples=1000). Os resultados são lidos com selected_indices(), num_selected(), get_support(). solver="local_search" não requer licença; "sa", "kaiwu_cim" usam o Kaiwu SDK e requerem licença. O tempo de update_mask é dominado pela resolução do QUBO e projeção de cardinalidade, crescendo rapidamente com o número de características (cerca de 13-15 segundos para 400 características localmente, cálculo de derivadas leva menos de 1 segundo); hessian_mode e max_samples afetam apenas a parte das derivadas, reserve tempo de acordo com o número real de características. QuadraticLinearSolver().solve(Q, b) apenas converte o termo QUBO em uma matriz Ising com um spin auxiliar, não resolve.

Entrega e Aceitação

Para tarefas novas, entregue um script completo incluindo dados, importações, configuração, loop de treinamento e saída de resultados; ao modificar código existente, altere apenas a parte necessária para a tarefa. Quando apenas o plano ou registro do ambiente é solicitado, salve o documento especificado; após complementar requisitos em múltiplas iterações, atualize a entrega e verifique se o arquivo foi escrito. Fragmentos de QVAE/QDiffusion na documentação de referência são esboços estruturais contendo variáveis de contexto e não podem ser usados como scripts diretamente executáveis. Quando a API não estiver clara, localize o kaiwu.torch_plugin.__file__ atual e consulte a assinatura real e o código-fonte. Relate o interpretador real, versões de dependências e resultados de execução; a aprovação do RBM não garante a aprovação de outros modelos, GPU ou CIM em nuvem.