confection

Confecção: o sistema de configuração mais doce para Python

confection ? é uma biblioteca leve que oferece um sistema de configuração, permitindo que você descreva convenientemente árvores arbitrárias de objetos.

A configuração é um enorme desafio para o código de aprendizado de máquina, porque você pode expor quase todos os detalhes de qualquer função como hiperparâmetro. A configuração que você deseja expor pode estar arbitrariamente distante em sua pilha de chamadas, portanto, pode precisar passar por toda a API da CLI ou REST, através de qualquer número de funções intermediárias, afetando a interface de tudo ao longo do caminho. E depois que essas configurações são adicionadas, elas se tornam difíceis de remover mais tarde. Os valores padrão também se tornam difíceis de mudar sem quebrar a compatibilidade com versões anteriores.

Para resolver esse problema, confection oferece um sistema de configuração que permite descrever facilmente árvores arbitrárias de objetos. Os objetos podem ser criados por meio de chamadas de função que você se registra usando uma sintaxe simples do decorador. Você pode até ver as funções que você cria, permitindo fazer melhorias sem quebrar a compatibilidade com versões anteriores. O sistema de configuração mais semelhante que estamos cientes é o Gin, que usa uma sintaxe semelhante, e também permite vincular o sistema de configuração às funções em seu código usando um decorador. O sistema de configuração da confection é mais simples e enfatiza um fluxo de trabalho diferente por meio de um subconjunto da funcionalidade de Gin.

⏳ Instalação

 PIP Instale a confecção

 Conda Install -C CONDA -FORGE CONFECÇÃO

Uso

O sistema de configuração analisa um arquivo .cfg como

 [Treinamento] Paciência = 10Dropout = 0.2USE_VETORS = FALSE [TREINING.LOGGING] Level = "Info" [NLP]# Isso usa o valor de treinamento.use_vettorsuse_vectors = $ {Training.use_vectors} lang = "en"

e resolve isso em um Dict :

 {"Treinamento": {"Paciência": 10, "Dropout": 0.2, "use_vectors": false, "Logging": {"nível": "info"}
  }, "nlp": {"use_vectors": false, "lang": "en"
  }
}

A configuração é dividida em seções, com o nome da seção em colchetes - por exemplo, [training] . Dentro das seções, os valores de configuração podem ser atribuídos às chaves usando = . Os valores também podem ser referenciados de outras seções usando a notação de pontos e os espaços reservados indicados pelo sinal do dólar e os aparelhos encaracolados. Por exemplo, ${training.use_vectors} receberá o valor de use_vectores no bloco de treinamento. Isso é útil para configurações compartilhadas entre os componentes.

O formato de configuração possui três diferenças principais em relação ao configparser interno do Python:

1. Valores formatados por JSON. confection passa todos os valores através do json.loads para interpretá -los. Você pode usar valores atômicos como strings, carros alegóricos, números inteiros ou booleanos, ou pode usar objetos complexos, como listas ou mapas.

2. Seções estruturadas. confection usa uma notação de pontos para construir seções aninhadas. Se você tiver uma seção chamada [section.subsection] , confection analisa isso em uma estrutura aninhada, colocando a subseção na seção.

3. Referências às funções de registro. Se uma chave começar com @ , confection interpretará seu valor como o nome de um registro de função, carregue a função registrada para esse nome e passará no restante do bloco como argumentos. Se as dicas do tipo estiverem disponíveis na função, os valores do argumento (e o valor de retorno da função) serão validados contra eles. Isso permite expressar configurações complexas, como um pipeline de treinamento em que batch_size é preenchido por uma função que gera flutuações.

Não há esquema predefinido que você deve seguir; Como você configura as seções de nível superior depende de você. No final, você receberá um dicionário com os valores que você pode usar no seu script - seja funções inicializadas completas ou apenas configurações básicas.

Por exemplo, digamos que você queira definir um novo otimizador. Você definiria seus argumentos em config.cfg como assim:

 [otimizer] @Optimizers = "my_cool_optimizer.v1" Learn_rate = 0.001Gamma = 1e-8

Para carregar e analisar esta configuração usando um registro catalogue (instale catalogue separadamente):

 Importar dataclasses da união de importação, iterableImport Cataloga de Registro de Importação de Conformação, Config# Crie um novo Registry.registry.Optimizers = Catalogue.Create ("Confeção", "Optimizers", Entry_Points = false)# Define uma classe dummytizer. MyCooloPtimizer: Learn_rate: Floatgamma: [email protected] ("my_cool_optimizer.v1") def make_my_optimizer (Learn_rate: Union [float, iterable [float]], gama: float): return mycooloptimizer (aprendê e buscar o objeto de otimizador instanciado.config = Config (). From_disk ("./ config.cfg") resolvido = registry.resolve (config) otimizer = resolvido ["otimizer"] # mycooloptimizer (Learn_rate = 0.001, gama = 1e-08)

️ CUIDADO: Os verificadores de tipo como mypy marcarão a adição de novos atributos ao registry dessa maneira - ou seja, registry.new_attr = ... - como erros. Isso ocorre porque um novo atributo é adicionado à classe após a inicialização. Se você estiver usando o TypeCheckers, pode ignorar isso (por exemplo, com # type: ignore para mypy ) ou usar uma alternativa TypeSafe: em vez de registry.new_attr = ... , use setattr(registry, "new_attr", ...) .

Sob o capô, confection procurará a função "my_cool_optimizer.v1" no registro "otimizadores" e depois chamá -lo com os argumentos learn_rate e gamma . Se a função tiver anotações de tipo, também validará a entrada. Por exemplo, se learn_rate for anotado como um flutuador e a configuração definir uma string, confection aumentará um erro.

A documentação da Thinc oferece mais informações sobre o sistema de configuração:

• blocos recursivos

• Definindo argumentos posicionais variáveis

• usando interpolação

• usando registros personalizados

• Anotações de tipo avançado com pydantic

• Usando esquemas de base

• preenchendo uma configuração com padrões

API

Config de classe

Esta classe contém o modelo e a configuração de treinamento e pode carregar e salvar o formato de configuração no estilo INI de/para uma string, arquivo ou bytes. A classe Config é uma subclasse do dict e usa ConfigParser do Python sob o capô.

^{Config.__init__ do método .__ init____}

Inicialize um novo objeto Config com dados opcionais.

 Da confecção import configConfig = config ({"treinamento": {"Paciência": 10, "DROWOUT": 0.2}})

Argumento	Tipo	Descrição
data	Optional[Union[Dict[str, Any], Config]]	Dados opcionais para inicializar a configuração.
section_order	Optional[List[str]]	Nomes de seção de nível superior, em ordem, usados ​​para classificar a configuração salva e carregada. Todas as outras seções serão classificadas em ordem alfabética.
is_interpolated	Optional[bool]	Se a configuração está interpolada ou se contém variáveis. Leia dos data se for uma instância de Config e, de outra forma, padrão para True .

^{Método Config.from_str}

Carregue a configuração de uma string.

 Da confecção import configconfig_str = "" "[treinamento] paciência = 10dropout = 0.2" "" config = config (). from_str (config_str) print (config ["treinamento"]) # {'paciência': 10, 'abandono': 0,2}}

Argumento	Tipo	Descrição
text	str	A configuração da string para carregar.
interpolate	bool	Se deve interpolar variáveis ​​como ${section.key} . Padrões para True .
overrides	Dict[str, Any]	Substituições para valores e seções. As chaves são fornecidas na notação de pontos, por exemplo, "training.dropout" mapeado para o valor.
Retorna	Config	A configuração carregada.

^{Método Config.to_str}

Carregue a configuração de uma string.

 Da confeição import configConfig = config ({"treinamento": {"Paciência": 10, "DROWOUT": 0.2}}) print (config.to_str ()) # '[treinamento] npatience = 10nndropout = 0,2'

Argumento	Tipo	Descrição
interpolate	bool	Se deve interpolar variáveis ​​como ${section.key} . Padrões para True .
Retorna	str	A string config.

^{Método Config.to_bytes}

Serialize a configuração para uma string de byte.

 Da confeição import configConfig = config ({"treinamento": {"Paciência": 10, "DROWOUT": 0.2}}) config_bytes = config.to_bytes () print (config_bytes) # b '[treinamento] npatience = 10nndropout = 0.2'

Argumento	Tipo	Descrição
interpolate	bool	Se deve interpolar variáveis ​​como ${section.key} . Padrões para True .
overrides	Dict[str, Any]	Substituições para valores e seções. As chaves são fornecidas na notação de pontos, por exemplo, "training.dropout" mapeado para o valor.
Retorna	str	A configuração serializada.

^{Método Config.from_bytes}

Carregue a configuração de uma string de byte.

 Da confeição import configConfig = config ({"treinamento": {"paciência": 10, "abandono": 0.2}}) config_bytes = config.to_bytes () new_config = config (). from_bytes (config_bytes)

Argumento	Tipo	Descrição
bytes_data	bool	Os dados a serem carregados.
interpolate	bool	Se deve interpolar variáveis ​​como ${section.key} . Padrões para True .
Retorna	Config	A configuração carregada.

^{Método Config.to_disk}

Serialize a configuração para um arquivo.

 Da confeição import configConfig = config ({"treinamento": {"Paciência": 10, "DROWOUT": 0.2}}) config.to_disk ("./ config.cfg")

Argumento	Tipo	Descrição
path	Union[Path, str]	O caminho do arquivo.
interpolate	bool	Se deve interpolar variáveis ​​como ${section.key} . Padrões para True .

^{Método Config.from_disk}

Carregue a configuração de um arquivo.

 Da confeição import configconfig = config ({"treinamento": {"paciência": 10, "abandono": 0.2}}) config.to_disk ("./ config.cfg") new_config = config (). de_disk ("./ config.cfg ")

Argumento	Tipo	Descrição
path	Union[Path, str]	O caminho do arquivo.
interpolate	bool	Se deve interpolar variáveis ​​como ${section.key} . Padrões para True .
overrides	Dict[str, Any]	Substituições para valores e seções. As chaves são fornecidas na notação de pontos, por exemplo, "training.dropout" mapeado para o valor.
Retorna	Config	A configuração carregada.

^{Método Config.copy}

Cópia profunda a configuração.

Argumento	Tipo	Descrição
Retorna	Config	A configuração copiada.

^{Método Config.interpolate}

Variáveis ​​interpoladas como ${section.value} ou ${section.subsection} e retorne uma cópia da configuração com valores interpolados. Pode ser usado se uma configuração for carregada com interpolate=False , por exemplo, via Config.from_str .

 Da confeição import configconfig_str = "" "[hyper_params] abandono = 0.2 [treinamento] abandono = $ {hyper_params.dropout}" "" config = config (). de_str (config_str, interpolate = false) print (config ["" "] ) # {'abandono': '$ {hyper_params.dropout}'}} config = config.interpolate () print (config ["treinamento"]) # {'abandono': 0.2}}

Argumento	Tipo	Descrição
Retorna	Config	Uma cópia da configuração com valores interpolados.

^{Método Config.merge}

Deep-Merge Dois objetos de configuração, usando a configuração atual como padrão. Apenas mescla seções e dicionários e não outros valores, como listas. Os valores fornecidos nas atualizações são substituídos na configuração base e quaisquer novos valores ou seções são adicionados. Se um valor de configuração for uma variável como ${section.key} (por exemplo, se a configuração foi carregada com interpolate=False) , a variável será preferida , mesmo que as atualizações forneçam um valor diferente. Isso garante que as referências variáveis ​​não sejam destruídas por uma mesclagem.

️ Observe que os blocos que se referem às funções registrados usando a sintaxe @ só são mesclados se estiverem se referindo às mesmas funções. Caso contrário, a fusão poderia facilmente produzir configurações inválidas, pois diferentes funções podem levar argumentos diferentes. Se um bloco se referir a uma função diferente, ele será substituído.

 Da confeição import configbase_config_str = "" "[treinamento] paciência = 10dropout = 0.2" "" update_config_str = "" "[treinamento] abandono = 0.1max_epochs = 2000" "" base_config = config (). de_str (base_config_str) update_fig_fig = config (). ) .from_str (update_config_str) mesclado = Config (base_config) .merge (update_config) print (mescle ["treinamento"]) # {'paciência': 10, 'abandono': 0.1, 'max_epochs': 2000}

Argumento	Tipo	Descrição
overrides	Union[Dict[str, Any], Config]	As atualizações para se fundir na configuração.
Retorna	Config	Uma nova instância de configuração que contém a configuração mesclada.

Atributos de configuração

Argumento	Tipo	Descrição
is_interpolated	bool	Se os valores de configuração foram interpolados. Padrões para True e é definido como False se uma configuração for carregada com interpolate=False , por exemplo, usando Config.from_str .