confection

Confección: el sistema de configuración más dulce para Python

¿ confection ? es una biblioteca liviana que ofrece un sistema de configuración que le permite describir convenientemente árboles arbitrarios de objetos.

La configuración es un gran desafío para el código de aprendizaje automático porque es posible que desee exponer casi cualquier detalle de cualquier función como hiperparámetro. La configuración que desea exponer puede ser arbitrariamente lejos en su pila de llamadas, por lo que es posible que deba pasar por la API CLI o REST, a través de cualquier cantidad de funciones intermedias, que afectan la interfaz de todo en el camino. Y luego, una vez que se agregan esa configuración, se vuelven difíciles de eliminar más tarde. Los valores predeterminados también se vuelven difíciles de cambiar sin romper la compatibilidad hacia atrás.

Para resolver este problema, confection ofrece un sistema de configuración que le permite describir fácilmente árboles arbitrarios de objetos. Los objetos se pueden crear a través de las llamadas a la función que se registra utilizando una sintaxis decoradora simple. Incluso puede versión de las funciones que crea, lo que le permite realizar mejoras sin romper la compatibilidad con retroceso. El sistema de configuración más similar del que conocemos es GIN, que utiliza una sintaxis similar, y también le permite vincular el sistema de configuración con funciones en su código utilizando un decorador. El sistema de configuración de confection es más simple y enfatiza un flujo de trabajo diferente a través de un subconjunto de la funcionalidad de GIN.

⏳ Instalación

 Confección de instalación de PIP

 Conda install -c conda -forge confection

Uso

El sistema de configuración analiza un archivo .cfg como

 [entrenamiento] paciencia = 10dropout = 0.2use_vectors = false [entrenamiento

y lo resuelve a un Dict :

 {"entrenamiento": {"paciencia": 10, "desacuerdo": 0.2, "use_vectors": falso, "registro": {"nivel": "info"}
  }, "nlp": {"use_vectors": falso, "lang": "en"
  }
}

La configuración se divide en secciones, con el nombre de la sección en los soportes cuadrados, por ejemplo, [training] . Dentro de las secciones, los valores de configuración se pueden asignar a las claves usando = . Los valores también se pueden hacer referencia a otras secciones utilizando la notación de puntos y los marcadores de posición indicados por el signo del dólar y los aparatos ortopédicos. Por ejemplo, ${training.use_vectors} recibirá el valor de USE_VECTORS en el bloque de capacitación. Esto es útil para la configuración que se comparten en los componentes.

El formato de configuración tiene tres diferencias principales con respecto a configparser incorporado de Python:

1. Valores formatados en JSON. confection pasa todos los valores a través de json.loads para interpretarlos. Puede usar valores atómicos como cadenas, flotadores, enteros o booleanos, o puede usar objetos complejos como listas o mapas.

2. Secciones estructuradas. confection utiliza una notación de puntos para construir secciones anidadas. Si tiene una sección llamada [section.subsection] , confection lo analizará en una estructura anidada, colocando la subsección dentro de la sección.

3. Referencias a funciones de registro. Si una clave comienza con @ , confection interpretará su valor como el nombre de un registro de funciones, cargue la función registrada para ese nombre y pase en el resto del bloque como argumentos. Si hay sugerencias de tipo disponibles en la función, los valores del argumento (y el valor de retorno de la función) se validará contra ellos. Esto le permite expresar configuraciones complejas, como una tubería de entrenamiento donde batch_size está poblada por una función que produce flotadores.

No hay un esquema predefinido que deba seguir; La forma en que configuras las secciones de nivel superior depende de ti. Al final, recibirá un diccionario con los valores que puede usar en su script, ya sea funciones inicializadas completas o simplemente configuraciones básicas.

Por ejemplo, supongamos que desea definir un nuevo optimizador. Definiría sus argumentos en config.cfg así:

 [Optimizer] @Optimizers = "my_cool_optimizer.v1" learn_rate = 0.001gamma = 1e-8

Para cargar y analizar esta configuración utilizando un registro catalogue (instale catalogue por separado):

 importar datacLasses para escribir unión de importación, iterableMport Catáloga de confección Registro de importación, config# Crear un nuevo registro. Mycooloptimizer: learn_rate: floatgamma: [email protected] ("my_cool_optimizer.v1") def make_my_optimizer (learn_rate: union [float, iterable [float]], gamma: float): return mycooloptimizer (learn_rate, gamma)# Cargue el archivo de configuración del disco, resuelto It y buscar el objeto Optimizer instanciado.config = Config (). From_disk ("./ config.cfg") resuelto = registry.resolve (config) optimizer = resuelve ["optimizer"] # mycooloptimizer (learn_rate = 0.001, gamma = 1e-08)

️ PRECAUCIÓN: Los comprobantes de tipo como mypy marcarán agregar nuevos atributos al registry de esta manera - es decir, registry.new_attr = ... - como errores. Esto se debe a que se agrega un nuevo atributo a la clase después de la inicialización. Si está utilizando typecheckers, puede ignorar esto (por ejemplo, # type: ignore para mypy ) o usar una alternativa typesfe: en lugar de registry.new_attr = ... , use setattr(registry, "new_attr", ...) .

Debajo del capó, confection buscará la función "my_cool_optimizer.v1" en el registro "optimizadores" y luego lo llamará con los argumentos learn_rate y gamma . Si la función tiene anotaciones de tipo, también validará la entrada. Por ejemplo, si learn_rate se anota como un flotador y la configuración define una cadena, confection aumentará un error.

La documentación de Thinc ofrece más información sobre el sistema de configuración:

• bloques recursivos

• Definición de argumentos posicionales variables

• Usando la interpolación

• Uso de registros personalizados

• Anotaciones de tipo avanzado con Pydantic

• Usando esquemas base

• llenar una configuración con valores predeterminados

API

Config de clase

Esta clase contiene el modelo y la configuración de capacitación y puede cargar y guardar el formato de configuración de estilo INI de/a una cadena, archivo o bytes. La clase Config es una subclase de dict y usa ConfigParser de Python debajo del capó.

^{Método Config.__init__}

Inicialice un nuevo objeto Config con datos opcionales.

 Desde la importación de confección configConfig = config ({"entrenamiento": {"paciencia": 10, "abandono": 0.2}})

Argumento	Tipo	Descripción
data	Optional[Union[Dict[str, Any], Config]]	Datos opcionales para inicializar la configuración con.
section_order	Optional[List[str]]	Los nombres de la sección de nivel superior, en orden, utilizados para ordenar la configuración guardada y cargada. Todas las demás secciones se ordenarán alfabéticamente.
is_interpolated	Optional[bool]	Si la configuración está interpolada o si contiene variables. Lea de los data si es una instancia de Config y de otra manera vale la pena en True .

^{Método Config.from_str}

Cargue la configuración desde una cadena.

 Desde la importación de confección confconfig_str = "" "[capacitación] paciencia = 10dropout = 0.2" "" "config (). From_str (config_str) print (config [" entrenamiento "]) # {'paciencia': 10, 'abandono': 0.2}}

Argumento	Tipo	Descripción
text	str	La configuración de cadena para cargar.
interpolate	bool	Si interpolar variables como ${section.key} . El valor predeterminado es True .
overrides	Dict[str, Any]	Anula por valores y secciones. Las claves se proporcionan en notación de puntos, por ejemplo, "training.dropout" asignadas al valor.
Devolución	Config	La configuración cargada.

^{Método Config.to_str}

Cargue la configuración desde una cadena.

 Desde confection import confconfig = config ({"entrenamiento": {"paciencia": 10, "abandono": 0.2}}) print (config.to_str ()) # '[entrenamiento] npatience = 10nndropout = 0.2'

Argumento	Tipo	Descripción
interpolate	bool	Si interpolar variables como ${section.key} . El valor predeterminado es True .
Devolución	str	La configuración de cadena.

^{Método Config.to_bytes}

Serializa la configuración en una cadena de byte.

 Desde la importación de confección configConfig = config ({"entrenamiento": {"paciencia": 10, "desacuerdo": 0.2}}) config_bytes = config.to_bytes () print (config_bytes) # b '[entrenamiento] npatience = 10nndropout = 0.2' '

Argumento	Tipo	Descripción
interpolate	bool	Si interpolar variables como ${section.key} . El valor predeterminado es True .
overrides	Dict[str, Any]	Anula por valores y secciones. Las claves se proporcionan en notación de puntos, por ejemplo, "training.dropout" asignadas al valor.
Devolución	str	La configuración serializada.

^{Método Config.from_bytes}

Cargue la configuración desde una cadena de byte.

 Desde confection import confConfig = config ({"entrenamiento": {"paciencia": 10, "desacuerdo": 0.2}}) config_bytes = config.to_bytes () new_config = config (). From_bytes (config_bytes)

Argumento	Tipo	Descripción
bytes_data	bool	Los datos para cargar.
interpolate	bool	Si interpolar variables como ${section.key} . El valor predeterminado es True .
Devolución	Config	La configuración cargada.

^{Método Config.to_disk}

Serializa la configuración en un archivo.

 Desde la importación de confección configConfig = config ({"entrenamiento": {"paciencia": 10, "desacuerdo": 0.2}}) config.to_disk ("./ config.cfg")

Argumento	Tipo	Descripción
path	Union[Path, str]	La ruta del archivo.
interpolate	bool	Si interpolar variables como ${section.key} . El valor predeterminado es True .

^{Método Config.from_disk}

Cargue la configuración desde un archivo.

 Desde la importación de confección configConfig = config ({"entrenamiento": {"paciencia": 10, "desacuerdo": 0.2}}) config.to_disk ("./ config.cfg") new_config = config (). From_disk ("./ config.cfg ")

Argumento	Tipo	Descripción
path	Union[Path, str]	La ruta del archivo.
interpolate	bool	Si interpolar variables como ${section.key} . El valor predeterminado es True .
overrides	Dict[str, Any]	Anula por valores y secciones. Las claves se proporcionan en notación de puntos, por ejemplo, "training.dropout" asignadas al valor.
Devolución	Config	La configuración cargada.

^{método Config.copy}

Copia profunda La configuración.

Argumento	Tipo	Descripción
Devolución	Config	La configuración copiada.

^{Método Config.interpolate}

Variables interpoladas como ${section.value} o ${section.subsection} y devuelve una copia de la configuración con valores interpolados. Se puede usar si una configuración se carga con interpolate=False , por ejemplo, a través de Config.from_str .

 Desde la importación de confección confconfig_str = "" "[Hyper_params] desacoss = 0.2 [entrenamiento] desacoss = $ {hyper_params.dropout}" "" config = config (). From_str (config_str, interpolate = false) print (config ["entrenamiento"]] ) # {'Deltout': '$ {Hyper_params.dropout}'}} config = config.Interpolate () print (config ["entrenamiento"]) # {'desacuerdo': 0.2}}

Argumento	Tipo	Descripción
Devolución	Config	Una copia de la configuración con valores interpolados.

^{Método Config.merge}

Deep-ferge dos objetos de configuración, utilizando la configuración actual como el valor predeterminado. Solo fusiona secciones y diccionarios y no otros valores como listas. Los valores que se proporcionan en las actualizaciones se sobrescriben en la configuración base, y se agregan cualquier nuevo valor o sección. Si un valor de configuración es una variable como ${section.key} (por ejemplo, si la configuración se cargó con interpolate=False) , se prefiere la variable , incluso si las actualizaciones proporcionan un valor diferente. Esto asegura que las referencias variables no sean destruidas por una fusión.

️ Tenga en cuenta que los bloques que se refieren a funciones registradas utilizando la sintaxis @ solo se fusionan si se refieren a las mismas funciones. De lo contrario, la fusión podría producir fácilmente configuraciones no válidas, ya que diferentes funciones pueden tomar diferentes argumentos. Si un bloque se refiere a una función diferente, está sobrescribida.

 Desde la confección importar configbase_config_str = "" "[entrenamiento] paciencia = 10dropout = 0.2" "" "update_config_str =" "[entrenador] desacreditación = 0.1max_epochs = 2000" "" base_config = config (). From_str (base_config_str) update_config = config (config = config (configure ) .FROM_STR (update_config_str) fused = Config (base_config) .merge (update_config) imprime (fusionado ["entrenamiento"]) # {'paciencia': 10, 'abandono': 0.1, 'max_epochs': 2000}

Argumento	Tipo	Descripción
overrides	Union[Dict[str, Any], Config]	Las actualizaciones para fusionar en la configuración.
Devolución	Config	Una nueva instancia de configuración que contiene la configuración fusionada.

Atributos de configuración

Argumento	Tipo	Descripción
is_interpolated	bool	Si los valores de configuración han sido interpolados. El valor predeterminado es True y se establece en False si una configuración se carga con interpolate=False , por ejemplo, usando Config.from_str .