Составь примеры обратные данным: Урок 10. задачи, обратные данной — Математика — 2 класс

Сводка

Благодаря новому набору декларативных пользовательских интерфейсов разработка под Android может стать еще интереснее. Хотя Compose все еще находится в зачаточном состоянии, он уже дает многообещающие результаты, и сообщество очень воодушевлено этим. Есть достаточно сигналов, указывающих на то, что Compose де-факто станет способом создания приложений для Android.Он также снижает барьер для входа для многих не инженеров благодаря интуитивно понятным API-интерфейсам, которые легко понять.

Я надеюсь, что эта статья дала вам представление о том, что можно делать с помощью Jetpack Compose. Мне не терпится увидеть, как вы используете его для создания потрясающих мобильных приложений. Удачного сочинения!

Google: Jetpack Compose позволяет разработчикам Android писать приложения с «значительно меньшим объемом кода»

Все сеансы Transform 2021 теперь доступны по запросу.Смотри.

Сегодня Google выпустила альфа-версию Jetpack Compose, своего набора инструментов пользовательского интерфейса, чтобы помочь разработчикам «создавать красивый пользовательский интерфейс для всех платформ Android с собственным доступом к API платформы». Хотя альфа-версия означает, что она определенно не готова к производству, Jetpack Compose обещает позволить разработчикам Android создавать приложения с использованием «значительно меньшего количества кода, интерактивных инструментов и интуитивно понятных API-интерфейсов Kotlin». Альфа-версия также включает новые инструменты, включая анимацию, макеты ограничений и оптимизацию производительности.

Android Jetpack, который Google представил на конференции разработчиков I / O 2018, представляет собой набор компонентов для ускорения разработки приложений. Думайте об этом как о преемнике Support Library, набора компонентов, которые упрощают использование новых функций Android при сохранении обратной совместимости. Jetpack Compose, который Google впервые продемонстрировал на конференции разработчиков I / O 2019, представляет собой разукрупненный инструментарий, предназначенный для упрощения разработки пользовательского интерфейса путем объединения модели реактивного программирования с Kotlin.В июне Google пообещал, что Jetpack Compose выйдет в альфа-версии этим летом и выпустит версию 1.0 в следующем году. Первый шаг выполнен.

Низкий код и подходы без кода к разработке программного обеспечения в моде. Все, от стартапов до технологических гигантов, пытаются упростить работу разработчика. Поэтому неудивительно, что Google стремится упростить разработку своей крупнейшей платформы - по состоянию на май 2019 года у Android было более 2,5 миллиардов активных устройств в месяц.

Реактивный ранец Compose Alpha

Google утверждает, что разработчики предпочитают декларативные API для создания пользовательского интерфейса.Таким образом, Jetpack Compose сочетает в себе «API-интерфейсы для высококачественных масштабируемых приложений, интуитивно понятный язык и модель реактивного программирования». Команда создала набор инструментов с учетом возможности взаимодействия - он совместим с представлениями Android и кодом Android, поэтому разработчики могут использовать его без необходимости переписывать свои приложения.

Кроме того, Google написал API Compose вместе с набором канонических примеров приложений, использующих его Material Design. Примеры приложений Compose доступны на GitHub и непосредственно в Android Studio:

• Взаимодействие с представлениями (начните смешивать составные функции в существующем приложении)
• Анимации
• Ленивые списки
• Макет ограничения
• Материальные компоненты пользовательского интерфейса
• Тестирование
• Текст и редактируемый текст
• Тематика и графика
• Управление окнами
• Ввод и жесты
• Начальная поддержка A11Y
• Оптимизация производительности

Говоря об Android Studio, Google обновил версию 4.2 Canary с командой Jetbrains Kotlin, чтобы помочь создавать приложения с помощью Compose. Усовершенствования включают плагин компилятора Kotlin для генерации кода, аннотации Compose Preview, интерактивные предварительные просмотры Compose в реальном времени, развертывание отдельных компонентов Compose на любом устройстве, завершение Compose Code и API Sample Data для Compose.

Jetpack Compose в Android Studio разработан, чтобы помочь вам быстро итерировать пользовательский интерфейс вашего приложения. Вы можете предварительно просмотреть свои компоненты Compose в процессе сборки, не развертывая приложение на устройстве или эмуляторе.Чтобы создать предварительный просмотр макета, напишите компонуемую функцию, которая не принимает никаких параметров, и добавьте аннотацию @Preview.

Android Studio предоставляет интерактивный режим предварительного просмотра, который позволяет вам нажимать или вводить элементы пользовательского интерфейса, в то время как пользовательский интерфейс реагирует так, как если бы он был в установленном приложении. Вы также можете развернуть один составной компонент на устройстве или эмуляторе по умолчанию, чтобы опробовать свой пользовательский интерфейс без переустановки всего приложения или перехода к его местоположению. Android Studio создает новое действие, содержащее пользовательский интерфейс, созданный этой функцией, и развертывает его в вашем приложении на устройстве.

Совместимость с существующим кодом Android

Иерархия представлений Android обычно представлена ​​как дерево виджетов пользовательского интерфейса. Обновление пользовательского интерфейса обычно заключается в обходе дерева с использованием функций, которые изменяют внутреннее состояние виджета. Команда Android Jetpack не только считает это утомительным, но и отмечает, что обновление представлений вручную увеличивает вероятность ошибок.

Вот почему Jetpack Compose использует полностью декларативный компонентный подход. Вы описываете свой пользовательский интерфейс как функции, преобразующие данные в иерархию пользовательского интерфейса; при изменении базовых данных платформа Compose автоматически обновляет иерархию пользовательского интерфейса, ускоряя разработку и сокращая количество ошибок.

Но переход на новую структуру - это большое изменение для существующих проектов и кодовых баз. Таким образом, Google разработал Compose так же легко, как и Kotlin, - он полностью совместим с существующим кодом Android.

Если вы создаете новое приложение, Google надеется, что вы полностью реализуете свой пользовательский интерфейс с помощью Compose. Но, учитывая, что он все еще находится в стадии альфа, вам, вероятно, пока не стоит этого делать. Для существующих кодовых баз Google рекомендует один из двух способов объединения Compose с существующим дизайном пользовательского интерфейса:

• Добавьте элементы Compose в существующий пользовательский интерфейс, либо создав полностью новый экран на основе Compose, либо добавив элементы Compose в существующий фрагмент или макет представления.
• Добавьте элемент пользовательского интерфейса на основе представления в составные функции. Это позволяет вам добавлять виджеты, не являющиеся компонентами Compose, например MapView или WebView, в дизайн на основе Compose.

Чтобы начать работу с Jetpack Compose, ознакомьтесь с Учебным пособием по составлению, настройкой и путём создания. Вы также можете попробовать MDC Compose Theme Adapter, который позволяет повторно использовать темы компонентов материала в пользовательском интерфейсе Compose.

VentureBeat

• актуальная информация по интересующим вас вопросам
• наши информационные бюллетени
• закрытый контент для лидеров мысли и доступ со скидкой к нашим призовым мероприятиям, таким как Transform 2021 : Узнать больше
• сетевые функции и многое другое

State and Jetpack Compose | Разработчики Android

Состояние в приложении - это любое значение, которое может меняться со временем.Это очень широкий определение и охватывает все, от базы данных комнаты до переменной в учебный класс.

Все приложения Android отображают состояние для пользователя. Несколько примеров состояния в Android приложений:

• Закусочная, которая показывает, когда сетевое соединение не может быть установлено.
• Сообщение в блоге и связанные с ним комментарии.
• Анимация пульсации на кнопках, которая воспроизводится, когда пользователь нажимает на них.
• Наклейки, которые пользователь может нарисовать поверх изображения.

Jetpack Compose поможет вам четко указать, где и как вы храните и используете состояние в приложении для Android.В этом руководстве основное внимание уделяется связи между состоянием и composables и API, которые Jetpack Compose предлагает для работы с состоянием. с легкостью.

Состояние и состав

Compose является декларативным, и поэтому единственный способ обновить его - вызвать тот же составной с новыми аргументами. Эти аргументы представляют Состояние пользовательского интерфейса. Каждый раз, когда состояние обновляется, происходит перекомпозиция . Как в результате такие элементы, как TextField , не обновляются автоматически, как в императивные представления на основе XML.Композиционному объекту должно быть явно указано новое состояние. для соответствующего обновления.

  @Composable
fun HelloContent () {
   Столбец (модификатор = Modifier.padding (16.dp)) {
       Текст(
           text = "Привет!",
           modifier = Modifier.padding (bottom = 8.dp),
           style = MaterialTheme.typography.h5
       )
       OutlinesTextField (
           значение = "",
           onValueChange = {},
           label = {Текст ("Имя")}
       )
   }
}
  

Если вы запустите это, вы увидите, что ничего не происходит.Это потому, что TextField не обновляется - он обновляется при изменении значения параметра и . Это из-за того, как композиция и перекомпоновка работают в Compose.

Ключевой термин: Состав: описание пользовательского интерфейса, созданного Jetpack Compose при выполнении составных компонентов.

Исходная композиция: создание композиции путем запуска композитные материалы впервые.

Перекомпоновка: повторный запуск компонентов для обновления композиции при изменении данных.

Чтобы узнать больше о начальной композиции и перекомпоновке, см. Думая в сочинении.

Состояние в составных частях

Составные функции могут сохранять в памяти один объект с помощью помню составной. Значение, вычисленное с помощью запоминающего , сохраняется в композиции во время начальная композиция, а сохраненное значение возвращается во время перекомпоновки. помните, что можно использовать для хранения как изменяемых, так и неизменяемых объектов.

mutableStateOf создает наблюдаемый MutableState , который является наблюдаемым типом, интегрированным со средой выполнения compose.

  интерфейс MutableState : State  {
    переопределить значение переменной: T
}
  

Любые изменения в значении будут планировать перекомпоновку любых составляемых функций которые читают значение . В случае ExpandingCard , всякий раз, когда расширяет изменения, это вызывает перекомпоновку ExpandingCard .

Есть три способа объявить объект MutableState в компонуемом объекте:

• val mutableState = запомнить {mutableStateOf (по умолчанию)}
• значение var по запоминанию {mutableStateOf (по умолчанию)}
• val (значение, setValue) = запомнить {mutableStateOf (по умолчанию)}

Эти объявления эквивалентны и предоставляются в качестве синтаксического сахара для различные варианты использования состояния. Вы должны выбрать тот, который производит самый простой для чтения код в компонуемом компоненте, который вы пишете.

Синтаксис делегата на требует следующего импорта:

  импорт androidx.compose.runtime.getValue
импортировать androidx.compose.runtime.setValue
  

Вы можете использовать запомненное значение как параметр для других компонентов или даже как логика в операторах для изменения отображаемых составных элементов. Например, если вы не хотите отображать приветствие, если имя пустое, используйте состояние в if выписка:

  @Composable
fun HelloContent () {
   Столбец (модификатор = Модификатор.padding (16.dp)) {
       имя переменной запомните {mutableStateOf ("")}
       if (name.isNotEmpty ()) {
           Текст(
               text = "Привет, $ name!",
               modifier = Modifier.padding (bottom = 8.dp),
               style = MaterialTheme.typography.h5
           )
       }
       OutlinesTextField (
           значение = имя,
           onValueChange = {name = it},
           label = {Текст ("Имя")}
       )
   }
}
  

Хотя помнит, что помогает сохранять состояние при перекомпоновке, состояние не сохраняется при изменении конфигурации.Для этого вы должны использовать запомнить Сохранение . RememberSaveable автоматически сохраняет любое значение, которое может быть сохранено в пакете . Для других значений вы можете передать настраиваемый объект заставки.

Другие поддерживаемые типы состояний

Jetpack Compose не требует использования MutableState для хранения состояния. Jetpack Compose поддерживает другие наблюдаемые типы. Перед прочтением другого наблюдаемый тип в Jetpack Compose, вы должны преобразовать его в состояние State , чтобы Jetpack Compose может автоматически перекомпоноваться при изменении состояния.

Составьте корабли с функциями для создания State из общих наблюдаемых типов используется в приложениях для Android:

Вы можете создать функцию расширения для Jetpack Compose, чтобы читать другие наблюдаемые объекты. типы, если ваше приложение использует настраиваемый наблюдаемый класс. См. Реализацию встроенные функции для примеров того, как это сделать. Любой объект, который позволяет Jetpack Compose для подписки на каждое изменение можно преобразовать в состояние State и прочитать его составной.

Ключевой момент: Compose автоматически перекомпоновывается после чтения Состояние объекты.

Если вы используете другой наблюдаемый тип, например LiveData в Составьте, вы должны преобразовать его в состояние State , прежде чем читать в компонуемом виде с помощью функции расширения, например LiveData .observeAsState () .

Осторожно: Использование изменяемых объектов, таких как ArrayList или mutableListOf () как состояние в Compose приведет к тому, что ваши пользователи увидят неверные или устаревшие данные в вашем приложении.

Изменяемые объекты, которые нельзя наблюдать, например ArrayList или изменяемый класс данных, не может быть обнаружен Compose запускает перекомпоновку, когда они меняются.

Вместо использования ненаблюдаемых изменяемых объектов мы рекомендуем использовать наблюдаемый держатель данных, такой как State > и неизменяемый listOf () .

Stateful в сравнении с сохранением состояния

Составной объект, который использует запоминание для хранения объекта, создает внутреннее состояние, создание составного с сохранением состояния . HelloContent - пример с отслеживанием состояния составной, потому что он сохраняет и изменяет свое имя состояние внутри. Это может быть полезным в ситуациях, когда вызывающему абоненту не нужно контролировать состояние и он может использовать его без необходимости самостоятельно управлять состоянием. Однако совместимость с внутреннее состояние, как правило, менее пригодно для повторного использования и труднее тестировать.

Составной компонент без сохранения состояния - это составной компонент, не содержащий состояния. Легко способ добиться безгражданства - использовать состояние подъем.

Когда вы разрабатываете повторно используемые компоненты, вы часто хотите предоставить как и версия того же составного объекта без сохранения состояния. Версия с сохранением состояния удобно для абонентов, которым нет дела до состояния, и для лиц без гражданства версия необходима для вызывающих абонентов, которым необходимо контролировать или поднимать состояние.

Государственный подъемник

Поднятие состояния в Compose - это шаблон перемещения состояния к вызывающему компоненту чтобы сделать составной объект без состояния. Общая схема подъема состояния в Jetpack Compose заменяет переменную состояния двумя параметрами:

• значение: T : текущее значение для отображения
• onValueChange: (T) -> Unit : событие, которое запрашивает изменение значения, где T - предлагаемое новое значение

Однако вы не ограничены onValueChange .Если более конкретные события подходит для составного, вы должны определить их, используя лямбды, такие как ExpandingCard работает с onExpand и onCollapse .

Состояние, которое поднимается таким образом, имеет несколько важных свойств:

• Единый источник истины: Перемещая состояние вместо его дублирования, мы обеспечение только одного источника истины. Это помогает избежать ошибок.
• Инкапсулировано: Только составные объекты с отслеживанием состояния смогут изменять свои штат.Это полностью внутреннее.
• Совместное использование: Поднятое состояние может использоваться несколькими компонентами. Скажи мы хотел, чтобы назвал в другом компонуемом файле, подъем позволил бы нам сделать тот.
• Interceptable: вызывающие компоненты без сохранения состояния могут решить игнорировать или изменять события перед изменением состояния.
• Decoupled: состояние для не имеющего состояния ExpandingCard может быть сохранено где угодно. Например, теперь можно переместить name в ViewModel .

В данном примере вы извлекаете имя и onValueChange из HelloContent и переместите их вверх по дереву на HelloScreen , который вызывает HelloContent .

  @Composable
fun HelloScreen () {
    имя переменной от RememberSaveable {mutableStateOf ("")}

    HelloContent (name = name, onNameChange = {name = it})
}

@Composable
весело HelloContent (name: String, onNameChange: (String) -> Unit) {
    Столбец (модификатор = Модификатор.padding (16.dp)) {
        Текст(
            text = "Привет, $ name",
            modifier = Modifier.padding (bottom = 8.dp),
            style = MaterialTheme.typography.h5
        )
        OutlinesTextField (
            значение = имя,
            onValueChange = onNameChange,
            label = {Текст ("Имя")}
        )
    }
}
  

Поднимая состояние из HelloContent , легче рассуждать о составной, повторно используйте его в разных ситуациях и протестируйте. HelloContent - это независимо от того, как его состояние хранится.Разделение означает, что если вы измените или замените HelloScreen , вам не нужно менять, как HelloContent реализовано.

Паттерн, при котором состояние понижается, а события растут, называется однонаправленный поток данных . В этом случае состояние понижается с HelloScreen до HelloContent , а события повышаются с HelloContent до HelloScreen . По следуя однонаправленному потоку данных, вы можете разделить составные элементы, отображающие состояние в пользовательском интерфейсе из частей вашего приложения, которые хранят и изменяют состояние.

Ключевой момент: При поднятии состояния существуют три правила, которые могут помочь вы выясняете, куда должно идти состояние:

1. Состояние должно быть повышено до минимум наименьшего общего родительский всех компонентов, которые используют состояние (чтение).
2. Состояние должно быть поднято до минимум наивысшего уровня, который он может заменить (написать).
3. Если два состояния изменяются в ответ на одни и те же события , они должны быть подняты вместе.

Вы можете поднять состояние выше, чем требуют эти правила, но не поднять состояние затруднит или сделает невозможным отслеживание однонаправленных данных поток.

ViewModel и состояние

ViewModels - рекомендуемые держатели состояний для композитных материалов, находящихся на высоком уровне дерево пользовательского интерфейса Compose или составные элементы, которые являются пунктами назначения в навигации библиотека. ViewModels сохраняют изменения конфигурации, поэтому они позволяют инкапсулировать состояние и события, связанные с пользовательским интерфейсом, без необходимости иметь дело с жизненный цикл активности или фрагмента, на котором размещается ваш код Compose.

Ваши ViewModels должны отображать состояние в наблюдаемом держателе, таком как LiveData или StateFlow . Когда объект состояния читается во время композиции, текущий объем перекомпоновки композиции автоматически подписывается на обновления этого объекта состояния.

У вас может быть один или несколько наблюдаемых держателей состояния - каждый из них должен владеть состояние для частей экрана, которые концептуально связаны и которые меняются все вместе. Таким образом, вы сохраните единый источник истины, даже если состояние используется в нескольких составных объектах.

Вы можете использовать LiveData и ViewModel в Jetpack Compose для реализации однонаправленный поток данных. Пример HelloScreen будет реализован с использованием ViewModel как это:

  class HelloViewModel: ViewModel () {

    // LiveData хранит состояние, которое наблюдает пользовательский интерфейс
    // (состояние стекает из ViewModel)
    частный val _name = MutableLiveData ("")
    имя val: LiveData  = _name

    // onNameChange - это определяемое нами событие, которое пользовательский интерфейс может вызывать
    // (события исходят из пользовательского интерфейса)
    fun onNameChange (newName: String) {
        _название.значение = новое имя
    }
}

@Composable
весело HelloScreen (helloViewModel: HelloViewModel = viewModel ()) {
    // по умолчанию viewModel () следует за жизненным циклом как за действием или фрагментом
    // который вызывает HelloScreen (). Этот жизненный цикл может быть изменен вызывающими HelloScreen.

    // имя - текущее значение [helloViewModel.name]
    // с начальным значением ""
    имя val: строка от helloViewModel.name.observeAsState ("")
    HelloContent (name = name, onNameChange = {helloViewModel.onNameChange (it)})
}

@Composable
весело HelloContent (name: String, onNameChange: (String) -> Unit) {
    Столбец (модификатор = Модификатор.padding (16.dp)) {
        Текст(
            text = "Привет, $ name",
            modifier = Modifier.padding (bottom = 8.dp),
            style = MaterialTheme.typography.h5
        )
        OutlinesTextField (
            значение = имя,
            onValueChange = onNameChange,
            label = {Текст ("Имя")}
        )
    }
}
  

Наблюдать за государством наблюдает за LiveData и возвращает обновленный объект State всякий раз, когда изменяется LiveData . State - наблюдаемый тип, который Jetpack Compose можно использовать напрямую. ObserverAsState будет наблюдать LiveData только в то время как он есть в составе.

Линия:

  val name: строка, созданная helloViewModel.name.observeAsState ("")
  

... это синтаксический сахар для автоматического разворачивания возвращаемого объекта состояния автор: ObserverAsState .Вы также можете назначить объект состояния с помощью присвоения оператор ( = ), что делает его State вместо String :

  val nameState: Состояние  = helloViewModel.name.observeAsState ("")
  

Восстановление состояния в Compose

Используйте RememberSaveable , чтобы восстановить состояние пользовательского интерфейса после действия или процесса воссоздан. RememberSaveable сохраняет состояние после перекомпоновки.Кроме того, RememberSaveable также сохраняет состояние через деятельность и процесс отдыха.

Способы хранения состояния

Все типы данных, которые добавляются к Bundle , сохраняются автоматически. если ты хотите сохранить то, что нельзя добавить в Bundle , есть несколько опции.

Участок

Самое простое решение - добавить @Parcelize аннотация к объекту. Объект становится посылочным, и его можно связать.Для Например, этот код создает пакетный тип данных City и сохраняет его в штат.

  @Parcelize
класс данных City (имя val: строка, страна val: строка): Parcelable

@Composable
fun CityScreen () {
    var selectedCity = RememberSaveable {
        mutableStateOf (Город ("Мадрид", "Испания"))
    }
}
  

MapSaver

Если по какой-либо причине @Parcelize не подходит, вы можете использовать mapSaver для определите собственное правило преобразования объекта в набор значений, которые Система может сохранять в Bundle .

  класс данных Город (имя val: строка, страна val: строка)

val CitySaver = run {
    val nameKey = "Имя"
    val countryKey = "Страна"
    mapSaver (
        save = {mapOf (nameKey to it.name, countryKey to it.country)},
        restore = {Город (он [nameKey] как String, он [countryKey] как String)}
    )
}

@Composable
fun CityScreen () {
    var selectedCity = RememberSaveable (stateSaver = CitySaver) {
        mutableStateOf (Город ("Мадрид", "Испания"))
    }
}
  

ListSaver

Чтобы избежать необходимости определять ключи для карты, вы также можете использовать listSaver и использовать его индексы в качестве ключей:

  класс данных City (имя val: строка, страна val: строка)

val CitySaver = listSaver <Город, Любой> (
    save = {listOf (это.имя, it.country)},
    restore = {Город (он [0] как Строка, он [1] как Строка)}
)

@Composable
fun CityScreen () {
    var selectedCity = RememberSaveable (stateSaver = CitySaver) {
        mutableStateOf (Город ("Мадрид", "Испания"))
    }
}
  

Узнать больше

Чтобы узнать больше о состоянии и Jetpack Compose, выберите Using State в Jetpack. Составьте codelab.

Версии файла Compose и обновление

Расчетное время чтения: 15 минут

Файл Compose - это файл YAML, определяющий службы, сети и тома для приложения Docker.

Форматы файлов Compose теперь описаны в этих справочных материалах для каждой версии.

В следующих темах объясняются различия между версиями Docker Engine. совместимость и способ обновления.

Матрица совместимости

Существует несколько версий формата файла Compose - 1, 2, 2.x и 3.x

В этой таблице показано, какие версии файлов Compose поддерживают определенные выпуски Docker.

В дополнение к версиям формата файла Compose, указанным в таблице, функция Compose сам находится в графике выпуска, как показано в Compose выпуски, но версии в формате файлов не обязательно увеличивать с каждым выпуском.Например, формат файла Compose 3.0 был впервые представлен в выпуске Compose 1.10.0 и версиями постепенно в последующих выпусках.

Последний формат файла Compose определяется спецификацией Compose и реализован в Docker Compose 1.27.0+ .

Ищете более подробную информацию о совместимости Docker и Compose?

Мы рекомендуем как можно чаще обновлять новейшие версии. Однако, если вы используете старую версию Docker и хотите определить, какой Версия Compose совместима, см. Версию Compose Примечания.Каждый набор примечаний к выпуску дает подробную информацию о том, какие версии Docker Engine поддерживаются, а также с совместимыми версиями формата файла Compose. (См. Также обсуждение в выпуск №3404.)

Подробнее о версиях и способах обновления см. Управление версиями и Обновление.

Управление версиями

Существуют три устаревшие версии формата файла Compose:

• Версия 1. Это определяется путем пропуска ключа версии в корне YAML.

• Версия 2.x. Это указывается с версией : '2', или версией : '2.1', и т. Д., Записью в корне YAML.

• версии 3.x, предназначенной для перекрестной совместимости между Compose и Docker Engine. режим роя. Это указывается с версией : '3', или версией : '3.1', и т. Д., Записью в корне YAML.

Последняя и рекомендуемая версия формата файла Compose определяется спецификацией Compose.Этот формат объединяет версии 2.x и 3.x и реализован в Compose 1.27.0+ .

v2 и v3 Декларация

Примечание : при указании версии файла Compose для использования убедитесь, что укажите и старший номер , и младший номер . Если дополнительная версия не указана, 0 используется по умолчанию, а не последняя дополнительная версия.

Матрица совместимости показывает версии файлов Compose, сопоставленные с выпусками Docker Engine.

Чтобы перенести проект на более позднюю версию, см. Обновление раздел.

Примечание : если вы используете несколько файлов Compose или расширяющие службы, каждый файл должен быть одна и та же версия - вы не можете, например, смешивать версии 1 и 2 в одном проект.

Некоторые вещи различаются в зависимости от того, какую версию вы используете:

• Структура и разрешенные ключи конфигурации
• Минимальная версия Docker Engine, которую вы должны использовать
• Поведение Compose в отношении сети

Эти различия объясняются ниже.

Версия 1 (устарело)

Файлы Compose, в которых не указана версия, считаются «версией 1». В тех файлы, все сервисы объявлен в корне документа.

Версия 1 поддерживается Compose до 1.6.x . Он будет объявлен устаревшим в будущий релиз Compose.

Файлы версии 1 не могут объявить именованные тома, сети или строить аргументы.

версии 2 поддерживаются Compose 1.6.0+ и требуется Docker Engine версии 1.10.0+ .

Именованные тома могут быть объявлены под тома ключ, и сети можно декларировать под сети ключ.

По умолчанию каждый контейнер присоединяется к сети по умолчанию в масштабе всего приложения и является обнаруживается на имени хоста, которое совпадает с именем службы. Это означает ссылки в основном не нужны. Подробнее см. Сеть в Compose.

Примечание

При указании используемой версии файла Compose убедитесь, что укажите и старший номер , и младший номер .Если дополнительная версия не указана, 0 используется по умолчанию, а не последняя дополнительная версия. В результате функции, добавленные в более поздних версиях, не будут поддерживаться. Например:

эквивалентно:

Простой пример:

  версия: "2.4"
Сервисы:
  Интернет:
    строить: .
    порты:
     - «5000: 5000»
    объемы:
     -.: / код
  Redis:
    изображение: redis
  

Более расширенный пример определения томов и сетей:

  версия: «2.4 "
Сервисы:
  Интернет:
    строить: .
    порты:
     - «5000: 5000»
    объемы:
     -.: / код
    сети:
      - передний ярус
      - задний ярус
  Redis:
    изображение: redis
    объемы:
      - redis-data: / var / lib / redis
    сети:
      - задний ярус
объемы:
  redis-data:
    водитель: местный
сети:
  передний ярус:
    водитель: мост
  задний ярус:
    водитель: мост
  

Было добавлено несколько других опций для поддержки сети, например:

• псевдонимы

• Параметр depends_on может использоваться вместо ссылок для обозначения зависимостей. между услугами и порядком запуска.

    версия: "2.4"
  Сервисы:
    Интернет:
      строить: .
      зависит от:
        - дб
        - Redis
    Redis:
      изображение: redis
    db:
      изображение: postgres
    

• ipv4_адрес , ipv6_address

Замена переменной также была добавлена ​​в версии 2.

Версия 2.1

Обновление версии 2, которое вводит только новые параметры доступно с Docker Engine версии 1.12.0+ . Файлы версии 2.1 поддерживается Compose 1.9.0+ .

Вводит следующие дополнительные параметры:

Версия 2.2

Обновление версии 2.1, в которой представлены только новые параметры. доступно с Docker Engine версии 1.13.0+ . Файлы версии 2.2 поддерживается Compose 1.13.0+ . Эта версия также позволяет указать номера шкалы по умолчанию в конфигурации службы.

Вводит следующие дополнительные параметры:

Версия 2.3

Обновление версии 2.2, которое вводит только новые параметры доступно с Docker Engine версии 17.06.0+ . Файлы версии 2.3 поддерживается Compose 1.16.0+ .

Вводит следующие дополнительные параметры:

Версия 2.4

Обновление версии 2.3, в которой представлены только новые параметры. доступно с Docker Engine версии 17.12.0+ . Файлы версии 2.4 поддерживается Compose 1.21.0+ .

Вводит следующие дополнительные параметры:

• платформа для определений услуг
• Поддержка полей расширения в корне службы, сети и тома определения

Версия 3

Предназначен для перекрестной совместимости между Compose и Docker Engine. режим роя, версия 3 удаляет несколько опций и добавляет еще несколько.

• Удалено: volume_driver , volume_from , cpu_shares , cpu_quota , cpuset , mem_limit , memswap_limit , extends , group_add . Видеть руководство по обновлению, чтобы узнать, как отказаться от них. (Для получения дополнительной информации о extends см. Расширение услуг.)

• Добавлено: развертывание

Примечание : при указании версии файла Compose для использования убедитесь, что укажите и старший номер , и младший номер .Если дополнительная версия не указана, 0 используется по умолчанию, а не последняя дополнительная версия. В результате в более поздние версии не поддерживаются. Например:

эквивалентно:

Версия 3.1

Обновление версии 3, которое вводит только новые параметры доступно с Docker Engine версии 1.13.1+ и выше.

Вводит следующие дополнительные параметры:

Версия 3.2

Обновление версии 3, которое вводит только новые параметры доступно с Docker Engine версии 17.04.0+ и выше.

Вводит следующие дополнительные параметры:

Версия 3.3

Обновление версии 3, которое вводит только новые параметры доступно с Docker Engine версии 17.06.0+ и выше.

Вводит следующие дополнительные параметры:

Версия 3.4

Обновление версии 3, которое вводит новые параметры. это доступно только с Docker Engine версии 17.09.0 и выше.

Вводит следующие дополнительные параметры:

Версия 3.5

Обновление версии 3, которое вводит новые параметры. это доступно только с Docker Engine версии 17.12.0 и выше.

Вводит следующие дополнительные параметры:

Версия 3.6

Обновление версии 3, которое вводит новые параметры. это доступно только с Docker Engine версии 18.02.0 и выше.

Вводит следующие дополнительные параметры:

Версия 3.7

Обновление версии 3, которое вводит новые параметры. это доступно только с Docker Engine версии 18.06.0 и выше.

Вводит следующие дополнительные параметры:

• init в определениях услуг
• rollback_config в конфигурациях развертывания
• Поддержка полей расширения в корне службы, сети, тома, секрета и определения конфигурации

Версия 3.8

Обновление версии 3, которое вводит новые параметры.это доступно только с Docker Engine версии 19.03.0 и выше.

Вводит следующие дополнительные параметры:

• max_replicas_per_node в размещении конфигурации
• template_driver опция для конфигурации и секретные конфигурации. Этот опция поддерживается только при развертывании служб роя с использованием стек докеров развернуть .
• драйвер и driver_opts вариант для секрета конфигурации.Эта опция поддерживается только при развертывании служб роя. используя стек докеров , разверните .

Обновление

Версии от 2.x до 3.x

Между версиями 2.x и 3.x структура файла Compose одинакова, но убрано несколько опций:

• volume_driver : вместо установки драйвера тома для службы определите том с использованием топ-уровень тома опцион и укажите там драйвер.

    версия: "3.9"
  Сервисы:
    db:
      изображение: postgres
      объемы:
        - данные: / var / lib / postgresql / data
  объемы:
    данные:
      драйвер: mydriver
    

• volume_from : Чтобы разделить том между сервисами, определите его с помощью топ-уровень тома опцион и ссылаться на него из каждой службы, которая его разделяет, используя уровень обслуживания тома вариант.

• cpu_shares , cpu_quota , cpuset , mem_limit , memswap_limit : Эти были заменены ключом ресурсов под развернуть .Развертывание Конфигурация вступает в силу только при использовании docker stack deploy и игнорируется docker-compose .

• extends : Этот параметр был удален для версии : "3.x" Составляйте файлы. (Для получения дополнительной информации см. Расширение услуг.)
• group_add : Эта опция была удалена для версии : "3.x" Компоновка файлов.
• pids_limit : Эта опция не была введена в версии : «3.x " Создание файлов.
• link_local_ips в сетях : эта опция не была представлена ​​в версия: "3.x" Составлять файлы.

Версии с 1 по 2.x

В большинстве случаев переход с версии 1 на 2 очень простой процесс:

1. Сделайте отступ для всего файла на один уровень и поместите вверху клавишу services: .
2. Добавьте строку версии: '2' вверху файла.

Сложнее, если вы используете определенные функции конфигурации:

• dockerfile : теперь он находится под ключом сборки :

    сборка:
    контекст:.dockerfile: Dockerfile-alternate
    

• log_driver , log_opt : теперь они живут под ключом ведения журнала :

    регистрация:
    драйвер: системный журнал
    опции:
      адрес системного журнала: "tcp: //192.168.0.42: 123"
    

• связывает с переменными среды: переменные среды, созданные ссылки, такие как CONTAINERNAME_PORT , `устарели в течение некоторого времени.В новой сетевой системе Docker они были удалены. Вы должны либо подключиться напрямую к соответствующее имя хоста или самостоятельно установите соответствующую переменную среды, используя ссылку hostname:

    Интернет:
    ссылки:
      - дб
    окружающая обстановка:
      - DB_PORT = tcp: // db: 5432
    

• external_links : Compose использует сети Docker при запуске версии 2 проекты, поэтому ссылки ведут себя немного иначе. В частности, два контейнеры должны быть подключены хотя бы к одной общей сети, чтобы общаться, даже если они явно связаны друг с другом.

  Подключите внешний контейнер к сеть по умолчанию или подключите внешний контейнер и контейнеров вашей службы в внешняя сеть.

• net : теперь заменено на network_mode:

    сеть: хост -> режим_сети: хост
  сеть: мост -> режим_сети: мост
  net: none -> network_mode: none
    

  Если вы используете net: "container: [название службы]" , теперь вы должны использовать network_mode: "service: [название службы]" вместо .

    net: "container: web" -> network_mode: "service: web"
    

  Если вы используете net: "container: [имя / идентификатор контейнера]" , значение не будет нужно изменить.

    net: "container: cont-name" -> network_mode: "container: cont-name"
  net: "container: abc12345" -> network_mode: "container: abc12345"
    

• тома с именованными томами: теперь они должны быть явно объявлены в раздел верхнего уровня тома вашего файла Compose.Если сервис устанавливает именованный том с именем data , вы должны объявить том data в своем верхнего уровня тома раздела. Весь файл может выглядеть так:

    версия: "2.4"
  Сервисы:
    db:
      изображение: postgres
      объемы:
        - данные: / var / lib / postgresql / data
  объемы:
    данные: {}
    

  По умолчанию Compose создает том с префиксом вашего имени. название проекта. Если вы хотите, чтобы он просто назывался data , объявите его как внешний:

    тома:
    данные:
      внешний: правда
    

Режим совместимости

docker-compose 1.20.0 представляет новый флаг --compatibility , предназначенный для помочь разработчикам упростить переход на версию 3. При включении docker-compose читает раздел deploy определения каждой службы и пытается преобразовать его в эквивалентный параметр версии 2. В настоящее время, переведены следующие ключи развертывания:

Все остальные клавиши игнорируются и выдают предупреждение, если они присутствуют. Вы можете просмотреть конфигурация, которая будет использоваться для развертывания с использованием --compatibility флаг с помощью команды config .

Не используйте это в производстве!

Мы не рекомендуем использовать режим --compatibility в производстве. Поскольку итоговая конфигурация является приблизительной с использованием режима без роя. свойства, это может привести к неожиданным результатам.

Составить ссылки на формат файла

Учебное пособие по загрузке и обработке данных - PyTorch Tutorials 0.2.0_4 документация

Автор : Сасанк Чиламкурти

Много усилий для решения любой задачи машинного обучения вкладывается в подготовка данных.PyTorch предоставляет множество инструментов для загрузки данных. легко и, надеюсь, сделает ваш код более читабельным. В этом руководстве мы увидим, как загружать и предварительно обрабатывать / дополнять данные из нетривиального набор данных.

Чтобы запустить это руководство, убедитесь, что следующие пакеты установлено:

• scikit-image : для изображения io и преобразования
• pandas : Для упрощения синтаксического анализа csv

 из __future__ import print_function, Division
импорт ОС
импортный фонарик
импортировать панд как pd
из skimage import io, преобразовать
импортировать numpy как np
import matplotlib.pyplot как plt
из torch.utils.data import Dataset, DataLoader
из torchvision import transforms, utils

# Игнорировать предупреждения
предупреждения об импорте
warnings.filterwarnings ("игнорировать")

plt.ion () # интерактивный режим
 

Набор данных, с которым мы будем иметь дело, - это поза лица. Это означает, что лицо аннотируется следующим образом:

Всего для каждого лица аннотировано 68 различных ориентиров.

Примечание

Загрузите набор данных отсюда чтобы изображения находились в каталоге с именем «faces /».Этот набор данных был на самом деле сгенерировано применением отличной позы dlib оценка на нескольких изображениях с сайта imagenet с тегом "лицо".

поставляется с файлом csv с аннотациями, который выглядит следующим образом:

 имя_образа, part_0_x, part_0_y, part_1_x, part_1_y, part_2_x, ..., part_67_x, part_67_y
0805personali01.jpg, 27,83,27,98, ... 84,134
1084239450_e76e00b7e7.jpg, 70,236,71,257, ..., 128,312
 

Давайте быстро прочитаем CSV и получим аннотации в массиве (N, 2), где N количество ориентиров.

 landmarks_frame = pd.read_csv ('faces / face_landmarks.csv')

n = 65
img_name = landmarks_frame.ix [n, 0]
landmarks = landmarks_frame.ix [n, 1:]. as_matrix (). astype ('float')
landmarks = landmarks.reshape (-1, 2)

print ('Имя изображения: {}'. формат (img_name))
print ('Форма ориентира: {}'. format (landmarks.shape))
print ('Первые 4 ориентира: {}'. формат (ориентиры [: 4]))
 

Давайте напишем простую вспомогательную функцию для отображения изображения и его ориентиров. и используйте его, чтобы показать образец.

 def show_landmarks (изображение, ориентиры):
    "" "Показать изображение с достопримечательностями" ""
    plt.imshow (изображение)
    plt.scatter (ориентиры [:, 0], ориентиры [:, 1], s = 10, marker = '.', c = 'r')
    plt.pause (0.001) # немного приостановить, чтобы графики обновились

plt.figure ()
show_landmarks (io.imread (os.path.join ('faces /', img_name)),
               ориентиры)
plt.show ()
 

Класс набора данных

torch.utils.data.Dataset - абстрактный класс, представляющий набор данных. Ваш собственный набор данных должен унаследовать Dataset и переопределить следующие методы:

• __len__ , так что len (набор данных) возвращает размер набора данных.
• __getitem__ для поддержки индексации, чтобы набор данных [i] мог использоваться для получения \ (i \) -го образца

Давайте создадим класс набора данных для нашего набора данных ориентиров лиц. Мы будем прочтите csv в __init__ , но оставьте чтение изображений __getitem__ . Это эффективно с точки зрения памяти, потому что не все изображения хранятся в памяти сразу, но читаются по мере необходимости.

Образец нашего набора данных будет диктовкой {'изображение': изображение, 'ориентиры': ориентиры} .Наш набор данных займет необязательный аргумент преобразовать , чтобы любая необходимая обработка могла быть нанесен на образец. Мы увидим полезность преобразования в следующий раздел.

 класс FaceLandmarksDataset (набор данных):
    "" "Набор данных Face Landmarks." ""

    def __init __ (self, csv_file, root_dir, transform = None):
        "" "
        Аргументы:
            csv_file (строка): путь к файлу csv с аннотациями.
            root_dir (строка): Каталог со всеми изображениями.transform (callable, optional): дополнительное преобразование, которое будет применяться
                по образцу.
        "" "
        self.landmarks_frame = pd.read_csv (csv_file)
        self.root_dir = корневой_ каталог
        self.transform = преобразовать

    def __len __ (сам):
        вернуть len (self.landmarks_frame)

    def __getitem __ (self, idx):
        img_name = os.path.join (self.root_dir, self.landmarks_frame.ix [idx, 0])
        изображение = io.imread (img_name)
        landmarks = self.landmarks_frame.ix [idx, 1:].as_matrix (). astype ('с плавающей точкой')
        landmarks = landmarks.reshape (-1, 2)
        sample = {'image': image, 'landmarks': ориентиры}

        если self.transform:
            sample = self.transform (образец)

        вернуть образец
 

Давайте создадим экземпляр этого класса и переберем образцы данных. Мы распечатает размеры первых 4 образцов и покажет их ориентиры.

 face_dataset = FaceLandmarksDataset (csv_file = 'faces / face_landmarks.csv',
                                    root_dir = 'лица /')

fig = plt.фигура()

для i в диапазоне (len (face_dataset)):
    sample = face_dataset [i]

    print (i, образец ['изображение']. форма, образец ['ориентиры']. форма)

    ax = plt.subplot (1, 4, i + 1)
    plt.tight_layout ()
    ax.set_title ('Образец № {}'. format (i))
    ax.axis ('выкл.')
    show_landmarks (** образец)

    если я == 3:
        plt.show ()
        сломать
 

Преобразовывает

Одна проблема, которую мы видим из вышеизложенного, заключается в том, что образцы не тот же размер. Большинство нейронных сетей ожидают изображения фиксированного размера.Следовательно, нам нужно будет написать некоторый код предварительной обработки. Создадим три преобразования:

• Изменить масштаб : масштабировать изображение
• RandomCrop : для произвольной обрезки изображения. Это данные увеличение.
• ToTensor : чтобы преобразовать изображения numpy в изображения torch (нам нужно поменять местами оси).

Мы будем писать их как вызываемые классы вместо простых функций, поэтому что параметры преобразования не нужно передавать каждый раз, когда называется.Для этого нам просто нужно реализовать метод __call__ и если требуется, метод __init__ . Затем мы можем использовать такое преобразование:

 tsfm = Преобразовать (параметры)
transformed_sample = tsfm (образец)
 

Посмотрите ниже, как эти преобразования применялись как к изображению, так и к ориентиры.

 класс Rescale (объект):
    "" "Измените масштаб изображения в образце до заданного размера.

    Аргументы:
        output_size (кортеж или кортеж): желаемый размер вывода. Если кортеж, вывод
            соответствует output_size.Если int, соответствует меньший из краев изображения
            to output_size с сохранением соотношения сторон.
    "" "

    def __init __ (self, output_size):
        assert isinstance (output_size, (число, кортеж))
        self.output_size = output_size

    def __call __ (self, sample):
        изображение, ориентиры = образец ['изображение'], образец ['ориентиры']

        h, w = image.shape [: 2]
        если isinstance (self.output_size, int):
            если h> w:
                new_h, new_w = self.output_size * h / w, self.output_size
            еще:
                new_h, new_w = self.output_size, self.output_size * w / h
        еще:
            new_h, new_w = self.output_size

        new_h, new_w = int (новый_h), int (новый_w)

        img = transform.resize (изображение, (new_h, new_w))

        # h и w меняются местами на ориентиры, потому что для изображений
        # Оси x и y - это оси 1 и 0 соответственно
        landmarks = ориентиры * [новое_н / нед, новое_ч / час]

        return {'изображение': img, 'ориентиры': ориентиры}


класс RandomCrop (объект):
    "" "Произвольная обрезка изображения в образце.Аргументы:
        output_size (кортеж или целое число): желаемый размер вывода. Если int, квадратная обрезка
            сделан.
    "" "

    def __init __ (self, output_size):
        assert isinstance (output_size, (число, кортеж))
        если isinstance (output_size, int):
            self.output_size = (размер_вывода, размер_вывода)
        еще:
            assert len ​​(output_size) == 2
            self.output_size = output_size

    def __call __ (self, sample):
        изображение, ориентиры = образец ['изображение'], образец ['ориентиры']

        h, w = изображение.форма [: 2]
        new_h, new_w = self.output_size

        top = np.random.randint (0, h - new_h)
        left = np.random.randint (0, w - новое_w)

        image = image [вверху: вверху + new_h,
                      left: left + new_w]

        landmarks = ориентиры - [слева, вверху]

        return {'изображение': изображение, 'ориентиры': ориентиры}


класс ToTensor (объект):
    "" "Преобразовать ndarrays в выборке в тензоры." ""

    def __call __ (self, sample):
        изображение, ориентиры = образец ['изображение'], образец ['ориентиры']

        # поменять местами ось цвета, потому что
        # numpy image: В x Ш x В
        # изображение фонарика: C X H X W
        изображение = изображение.транспонировать ((2, 0, 1))
        return {'image': torch.from_numpy (изображение),
                'ориентиры': torch.from_numpy (ориентиры)}
 

Составить преобразования

Теперь мы применяем преобразования к образцу.

Допустим, мы хотим изменить масштаб короткой стороны изображения до 256 и затем случайным образом вырежьте из него квадрат размером 224. то есть мы хотим составить Изменить масштаб преобразований и RandomCrop . torchvision.transforms.Compose - это простой вызываемый класс, который позволяет нам сделать это.

 = Изменить масштаб (256)
урожай = RandomCrop (128)
Compose = transforms.Compose ([Изменить масштаб (256),
                               RandomCrop (224)])

# Примените каждое из приведенных выше преобразований к образцу.
fig = plt.figure ()
sample = face_dataset [65]
для i, tsfrm в enumerate ([масштаб, кадрирование, составлено]):
    transformed_sample = tsfrm (образец)

    ax = plt.subplot (1, 3, i + 1)
    plt.tight_layout ()
    ax.set_title (тип (tsfrm) .__ name__)
    show_landmarks (** преобразованный_выборка)

plt.show ()
 

Перебор набора данных

Давайте соберем все это вместе и создадим набор данных со скомпонованными трансформируется.Подводя итог, каждый раз, когда производится выборка этого набора данных:

• Изображение считывается из файла на лету
• Преобразования применяются к считанному изображению
• Поскольку одно из преобразований является случайным, данные дополняются выборка

Мы можем перебирать созданный набор данных с для i в диапазоне петля, как и раньше.

 transformed_dataset = FaceLandmarksDataset (csv_file = 'faces / face_landmarks.csv',
                                           root_dir = 'лица /',
                                           преобразовать = преобразовывает.Составить ([
                                               Изменить масштаб (256),
                                               RandomCrop (224),
                                               ToTensor ()
                                           ]))

для i в диапазоне (len (transformed_dataset)):
    sample = transformed_dataset [i]

    print (i, образец ['изображение']. размер (), образец ['ориентиры']. размер ())

    если я == 3:
        сломать
 

Однако мы теряем много функций, используя простой цикл для для перебирать данные.В частности, мы упускаем:

• Пакетирование данных
• Перемешивание данных
• Загрузите данные параллельно, используя многопроцессорных рабочих.

torch.utils.data.DataLoader - это итератор, который предоставляет все эти Особенности. Параметры, используемые ниже, должны быть понятными. Один параметр проценты collate_fn . Вы можете указать, насколько именно нужны образцы для пакетирования с использованием collate_fn . Однако сортировка по умолчанию должна работать отлично подходит для большинства случаев использования.

 dataloader = DataLoader (transformed_dataset, batch_size = 4,
                        shuffle = True, num_workers = 4)


# Вспомогательная функция для отображения партии
def show_landmarks_batch (sample_batched):
    "" "Показать изображение с ориентирами для партии образцов." ""
    images_batch, landmarks_batch = \
            sample_batched ['изображение'], sample_batched ['ориентиры']
    batch_size = len (images_batch)
    im_size = images_batch.size (2)

    сетка = utils.make_grid (images_batch)
    plt.imshow (grid.numpy ().транспонировать ((1, 2, 0)))

    для i в диапазоне (batch_size):
        plt.scatter (landmarks_batch [i,:, 0] .numpy () + i * im_size,
                    landmarks_batch [i,:, 1] .numpy (),
                    s = 10, маркер = '.', c = 'r')

        plt.title ('Пакет из загрузчика данных')

для i_batch, sample_batched в перечислении (загрузчик данных):
    print (i_batch, sample_batched ['изображение']. size (),
          sample_batched ['ориентиры']. size ())

    # наблюдаем 4-ю партию и останавливаемся.
    если i_batch == 3:
        plt.figure ()
        show_landmarks_batch (sample_batched)
        plt.ось ('выкл')
        plt.ioff ()
        plt.show ()
        сломать
 

Послесловие: torchvision

В этом руководстве мы увидели, как писать и использовать наборы данных, преобразовывать и загрузчик данных. Пакет torchvision предоставляет некоторые общие наборы данных и трансформируется. Возможно, вам даже не придется писать собственные классы. Один из более общие наборы данных, доступные в torchvision, - это ImageFolder . Предполагается, что изображения организованы следующим образом:

 корень / муравьи / xxx.PNG
корень / муравьи / xxy.jpeg
корень / муравьи / xxz.png
.
.
.
корень / пчелы / 123.jpg
корень / пчелы / nsdf3.png
корень / пчелы / asd932_.png
 

, где «муравьи», «пчелы» и т. Д. Являются ярлыками класса. Аналогично общие преобразования которые работают с PIL.Image , например RandomHorizontalFlip , Scale , также доступны. Вы можете использовать их для записи загрузчика данных следующим образом:

 импортная горелка
из torchvision импорт преобразований, наборов данных

data_transform = transforms.Compose ([
        transforms.RandomSizedCrop (224),
        трансформируется.RandomHorizontalFlip (),
        transforms.ToTensor (),
        transforms.Normalize (среднее = [0,485, 0,456, 0,406],
                             std = [0,229, 0,224, 0,225])
    ])
hymenoptera_dataset = наборы данных.ImageFolder (root = 'hymenoptera_data / train',
                                           преобразование = преобразование_данных)
dataset_loader = torch.utils.data.DataLoader (hymenoptera_dataset,
                                             batch_size = 4, shuffle = True,
                                             num_workers = 4)
 

Пример с обучающим кодом см. Учебник по трансферному обучению.

Общее время работы скрипта: (0 минут 0,000 секунд)

Создано в Sphinx-Gallery

Руководство для начинающих по созданию классификатора изображений AI с использованием PyTorch | by Alexander Wu

Это пошаговое руководство по созданию классификатора изображений. Модель AI сможет научиться маркировать изображения. Я использую Python и Pytorch.

Когда мы пишем программу, очень сложно вручную кодировать каждое маленькое действие, которое мы выполняем. Иногда мы хотим использовать пакеты кода, которые уже написали другие люди.Эти упакованные подпрограммы называются библиотеками и могут быть добавлены в нашу программу путем их импорта и последующего обращения к библиотеке позже в коде.

Обычно мы импортируем все библиотеки в начале программы.

Вместо того, чтобы вводить длинное имя библиотеки всякий раз, когда мы ссылаемся на нее, мы можем сократить его до имени по нашему выбору, используя «as».

 # Библиотеки импорта 
 import torch 
 import torchvision.transforms as transforms 
 import torchvision.datasets как наборы данных 
 import torchvision.модели как модели 
 import torch.nn as nn 
 import torch.optim as optim 
 import numpy as np 
 from PIL import Image 
 import numpy as np 
 import matplotlib.pyplot as plt 

Далее мы хотим импортировать данные изображения наша модель ИИ будет извлекать уроки из.

Но перед этим нам нужно указать изменения, которые мы хотим выполнить с этими изображениями, поскольку та же команда, которая их импортирует, также преобразует данные.

Эти преобразования выполняются с помощью torchvision.преобразует библиотеку. Лучший способ понять преобразования - прочитать документацию здесь. Но я кратко расскажу, что делает каждая команда.

• преобразований. Compose позволяет нам составлять несколько преобразований вместе, поэтому мы можем использовать более одного преобразования.
• transforms.Resize ((255)) изменяет размер изображения так, чтобы самая короткая сторона имела длину 255 пикселей. Другая сторона масштабируется для сохранения соотношения сторон изображения.
• преобразовывает.CenterCrop (224) обрезает центр изображения, так что это квадратное изображение размером 224 на 224 пикселя.

Мы выполняем эти два шага, чтобы все изображения, входящие в нашу модель AI, имели одинаковый размер (модели AI не могут обрабатывать входные данные с разными размерами)

• преобразовывает. ToTensor () преобразует наше изображение в числа. Как оно это делает?
• Он разделяет три цвета, из которых состоит каждый пиксель нашего изображения: красный, зеленый и синий. По сути, это превращает одно изображение в три изображения (одно с красным оттенком, одно зеленое, одно синее).
• Затем он преобразует пиксели каждого тонированного изображения в яркость их цвета от 0 до 255. Эти значения делятся на 255, поэтому они могут находиться в диапазоне от 0 до 1. Наше изображение теперь является тензором Torch. (структура данных, в которой хранится множество чисел).
• transforms.Normalize (mean = [0,485, 0,456, 0,406], std = [0,229, 0,224, 0,225]) вычитает среднее из каждого значения и затем делит на стандартное отклонение.
• Мы будем использовать предварительно обученную модель, поэтому нам нужно использовать средства и стандартные отклонения, указанные в Pytorch.Для каждого изображения RGB есть три значения среднего и стандартного отклонения.

 # Укажите преобразования с помощью torchvision.transforms как преобразования 
 # librarytransformations = transforms.Compose ([
 transforms.Resize (255), 
 transforms.CenterCrop (224), 
 transforms.ToTensor (), 
 transforms.Normalize (mean) = [0,485, 0,456, 0,406], std = [0,229, 0,224, 0,225]) 
]) 

Наконец, мы можем импортировать наши изображения в программу. Мы используем библиотеку torchvision.datasets.

Прочтите об этом здесь.

Мы указываем два разных набора данных: один для изображений, на которых ИИ учится (обучающий набор), а другой - для набора данных, который мы используем для тестирования модели ИИ (набор проверки).

Команда datasets.ImageFolder () ожидает, что наши данные будут организованы следующим образом: root / label / picture.png. Другими словами, изображения следует рассортировать по папкам. Например, все изображения пчел должны быть в одной папке, все изображения муравьев - в другой и т. Д.

Мы даем команде

1. путь ко всем папкам и
2. преобразованиям, которые мы указали на предыдущем шаге.

 # Загрузить в каждый набор данных и применить преобразования, используя 
 # наборы torchvision.datasets как наборы данных librarytrain_set = datasets.ImageFolder ("root / label / train", transform = transformations) val_set = datasets.ImageFolder ("root / label / valid ", transform = transformations) 

Затем мы хотим поместить наши импортированные изображения в Dataloader.

Dataloader может выдавать случайные выборки наших данных, поэтому нашей модели не придется каждый раз иметь дело со всем набором данных. Это делает обучение более эффективным.

Мы указываем, сколько изображений мы хотим одновременно, в нашем batch_size (поэтому 32 означает, что мы хотим получить 32 изображения одновременно). Мы также хотим перетасовать наши изображения, чтобы они случайным образом вводились в нашу модель ИИ.

Прочтите о DataLoader здесь.

 # Вставить в загрузчик данных с помощью библиотеки torchtrain_loader = torch.utils.data.DataLoader (train_set, batch_size = 32, shuffle = True) val_loader = torch.utils.data.DataLoader (val_set, batch_size = 32, shuffle = True) 

Модели ИИ необходимо обучить на большом количестве данных, чтобы быть эффективным. Поскольку у нас не так много данных, мы хотим взять предварительно обученную модель (модель, которая ранее была обучена на многих изображениях), но адаптировать ее для распознавания наших конкретных изображений. Этот процесс называется трансферным обучением.

Модели распознавания изображений состоят из двух частей:

1. сверточной части и
2. классифицирующей части

Мы хотим сохранить предварительно обученную сверточную часть, но добавить наш собственный классификатор.Вот почему:

Раздел свертки / объединения нашей модели используется для распознавания функций внутри изображения. Сначала он определяет края, затем, используя края, он определяет формы и с помощью форм может идентифицировать объекты.

Но для обучения этого раздела требуется МНОГО данных - вероятно, больше, чем у нас - поэтому вместо этого мы можем использовать предварительно обученные сверточные слои по умолчанию. Эти предварительно обученные сверточные слои были обучены очень хорошо определять эти особенности, независимо от того, какое у вас изображение.

Есть также объединение слоев между сверточными слоями, которые сокращают изображение до меньшего размера, чтобы его можно было легко ввести в наш классификатор.

Последняя часть модели - классификатор. Классификатор берет всю информацию, извлеченную из фотографии в части свертки, и использует ее для идентификации изображения. Это часть предварительно обученной модели, которую мы хотим заменить и обучить на наших собственных изображениях. Это делает модель адаптированной для идентификации изображений, которые мы ей даем.

Мы используем библиотеку torchvision.models для загрузки предварительно обученной модели. Мы можем загрузить много разных моделей, и здесь можно найти дополнительную информацию. Я выбрал модель под названием densenet161 и указал, что мы хотим, чтобы она была предварительно обучена, установив pretrained = True.

Затем мы хотим убедиться, что мы не обучаем эту модель, поскольку она уже обучена, и мы хотим обучить только классификатор, который мы добавим в следующий раз. Мы говорим модели не вычислять градиенты какого-либо параметра, поскольку это делается только для обучения.

 # Получить предварительно обученную модель, используя torchvision.models в качестве библиотеки моделейmodel = models.densenet161 (pretrained = True) # Отключить обучение их параметров для param в model.parameters (): 
 param.requires_grad = False 

Теперь мы хотим заменить классификатор модели по умолчанию с нашим собственным классификатором. Классификаторы - это полностью связанные нейронные сети, поэтому для этого мы должны сначала построить нашу собственную нейронную сеть.

Нейронная сеть - это просто метод поиска сложных шаблонов и связей между числами входа и выхода.В этом случае для определения вероятности того, что изображение является определенной меткой, используются особенности изображения, которые были выделены секцией свертки.

Первое, что мы хотим сделать, это определить количество чисел, вводимых в нашу нейронную сеть. Это должно соответствовать количеству чисел, которое выводится из предыдущего раздела (сверточного раздела). Поскольку мы вообще не меняли сверточную секцию, количество чисел, вводимых в наш классификатор, должно быть таким же, как в классификаторе модели по умолчанию.

Далее мы хотим определить количество выходов. Это число должно соответствовать тому, сколько типов изображений у вас есть. Модель предоставит вам список процентов, каждое из которых соответствует тому, насколько изображение соответствует этой метке. Итак, если у вас есть изображения пчел, муравьев и мух, есть 3 метки. и в выходном слое должно быть 3 числа, каждое из которых соответствует вероятности того, что на входе пчела, муравей или муха.

Получив эти данные, мы используем библиотеку torch.nn для создания классификатора.Информацию можно найти здесь.

• nn. Последовательный может помочь нам сгруппировать несколько модулей вместе.
• nn.Linear определяет взаимодействие между двумя слоями. Мы даем ему 2 числа, определяя количество узлов в двух слоях.
• Например, в первом nn.Linear первый слой является входным, и мы можем выбрать, сколько чисел мы хотим во втором слое (я выбрал 1024).
• nn.ReLU - функция активации для скрытых слоев.Функции активации помогают модели изучить сложные отношения между входом и выходом. Мы используем ReLU на всех слоях, кроме вывода.

Мы повторяем это для сколь угодно большого количества скрытых слоев с любым количеством узлов в каждом слое.

• nn.LogSoftmax - функция активации для выхода. Функция softmax превращает выведенные числа в проценты для каждой метки, а функция журнала применяется для ускорения вычислений.Мы должны указать, что выходной слой является столбцом, поэтому мы устанавливаем размер равным 1.

После создания нашего собственного классификатора мы заменяем классификатор модели по умолчанию.

 # Создать новый классификатор для модели, используя torch.nn как nn libraryclassifier_input = model.classifier.in_features 
 num_labels = # ВВЕДИТЕ КОЛИЧЕСТВО ЭТИКЕТК В ВАШИХ ДАННЫХclassifier = nn.Sequential (nn.Linear (classifier_input, 1024), 
 nn .ReLU (), 
 nn.Linear (1024, 512), 
 nn.ReLU (), 
 nn.Linear (512, num_labels), 
 nn.LogSoftmax (dim = 1)) # Заменить классификатор по умолчанию новым classifiermodel.classifier = classifier 

Теперь модель создана! Далее нам просто нужно его потренировать.

Обучение модели на графическом процессоре происходит намного быстрее, чем на центральном процессоре. Поэтому, чтобы определить, какое устройство доступно для вас, мы используем Torch для проверки. Если есть совместимый графический процессор, мы устанавливаем переменную на графический процессор, если нет, он привязан к процессору. Затем мы перемещаем нашу модель на это устройство.

 # Найдите устройство, доступное для использования, используя torch librarydevice = torch.device ("cuda" if torch.cuda.is_available () else "cpu") # Переместить модель на устройство, указанное вышеmodel.to (device) 

Во время обучения нам нужно определить, насколько наша модель «выключена». Чтобы оценить количество ошибок в нашей модели, мы используем nn.NLLLoss . Эта функция принимает выходные данные нашей модели, для которой мы использовали функцию nn.LogSoftmax.

Чтобы обучить нашу модель, мы берем нашу ошибку и смотрим, как мы можем скорректировать веса, на которые мы умножили наши числа, чтобы получить наименьшую ошибку.Метод расчета того, как мы корректируем наши веса и применяем его к нашим весам, называется Адам. Мы используем библиотеку torch.optim, чтобы использовать этот метод и передать ему наши параметры.

 # Задайте функцию ошибки, используя torch.nn как nn librarycriterion = nn.NLLLoss () # Задайте функцию оптимизатора, используя torch.optim как optim libraryoptimizer = optim.Adam (model.classifier.parameters ()) 

Теперь мы обучаем . Мы хотим, чтобы наша модель проходила через весь набор данных несколько раз, поэтому мы используем цикл for. Каждый раз, когда он просматривает весь набор изображений, это называется эпохой.В одну эпоху мы хотим, чтобы модель прошла как обучающий набор, так и набор проверки.

Начнем с обучающего набора.

Сначала мы устанавливаем модель в режим обучения и используем цикл for для просмотра каждого изображения.

После перемещения изображений и меток на соответствующее устройство нам нужно очистить настройки весов, объявив optimizer.zero_grad () .

Затем мы можем вычислить выход нашей модели с учетом наших изображений и того, насколько «выключена» наша модель с ее выходными данными и правильными ответами.

Затем мы можем найти корректировки, которые нам необходимо внести, чтобы уменьшить эту ошибку, вызвав loss.backward () , и использовать наш оптимизатор для корректировки весов, вызвав optimizer.step () .

Во время обучения мы хотим знать, как идут дела, поэтому мы отслеживаем общие ошибки, которые мы рассчитали, и распечатываем ход обучения.

Переходим к валидационному набору.

Мы установили нашу модель в режим оценки и используем цикл for для перебора всех изображений в нашем наборе.

Мы повторяем шаги, которые мы предприняли для обучающего набора, чтобы получить выходные данные нашей модели и насколько наша модель «отстает» от реальных меток.

Наша модель использовала функцию LogSoftmax для увеличения скорости вычислений, но теперь нам нужны реальные проценты, а не проценты журнала. Поэтому мы используем torch.exp , чтобы обратить функцию журнала. Затем мы хотим увидеть, какой класс модель отнесла к нашим изображениям. .topk дает нам высший класс, который был угадан, и какой процент он угадал - нам важен только класс, поэтому мы можем игнорировать процент.

Чтобы определить, сколько изображений было угадано правильно, мы проверяем, какие угаданные классы равны реальным классам. Затем мы можем усреднить весь пакет, чтобы определить точность нашей модели (сколько изображений было угадано правильно, деленное на общее количество изображений).

После прохождения набора для обучения и проверки мы хотим распечатать ошибки для обоих и точность набора проверки.

 эпох = 10 
 для эпох в диапазоне (эпох): 
 train_loss = 0 
 val_loss = 0 
 precision = 0 
 # Обучение модели 
 model.train () 
 counter = 0 
 для входов, метки в train_loader: 
 # Перейти к устройству 
 inputs, labels = inputs.to (устройство), labels.to (устройство) 
 # Очистить оптимизаторы 
 optimizer.zero_grad () # Вперед pass 
 output = model.forward (input) # Loss 
 loss = criterion (output, labels) # Рассчитать градиенты (backpropogation) 
 loss.backward () # Настроить параметры на основе градиентов 
 optimizer.step () # Добавить потерю к rnning loss обучающего набора 
 train_loss + = loss.item () * inputs.size (0) 
 # Распечатать прогресс нашего обучения 
 counter + = 1 
 print (counter, "/", len (train_loader)) 
 
 # Оценка модели 
 model.eval () 
 counter = 0 
 # Сказать горелке, что градиенты 
 не рассчитывать с помощью torch.no_grad (): 
 для входов, метки в val_loader: 
 # Переместить на вход устройства 
, метки = inputs.to (устройство), labels.to (устройство) 
 # Прямой проход 
 output = model.forward (inputs) # Вычислить потери 
 valloss = критерий (output, labels) # Добавить потерю к текущим потерям валидационного набора 
 val_loss + = valloss.item () * inputs.size (0) 
 # Поскольку наша модель выводит LogSoftmax, найдите реальные 
 # проценты, изменив логарифмическую функцию 
 output = torch.exp (output) 
 # Получите высший класс вывода 
 top_p , top_class = output.topk (1, dim = 1) # Посмотрите, сколько классов было правильным? 
 equals = top_class == labels.view (* top_class.shape) # Вычислить среднее значение (получить точность для этой партии) 
 # и прибавить его к точности хода для этой эпохи 
 precision + = torch.mean (equals.type (torch.FloatTensor)). item () 
 # Распечатать прогресс нашей оценки 
 counter + = 1 
 print (counter, "/", len (val_loader)) 
 
 # Получить среднюю потерю для вся эпоха 
 train_loss = train_loss / len (train_loader.dataset) 
 valid_loss = val_loss / len (val_loader.dataset) 
 # Распечатайте информацию 
 print ('Accuracy:', precision / len (val_loader)) 
 print (' Эпоха: {} \ tПотеря обучения: {: .6f} \ tПотеря проверки: {: .6f} '. Format (epoch, train_loss, valid_loss)) 

Это было здорово! Вы только что создали классификатор изображений AI.Но теперь мы действительно хотим использовать его - мы хотим дать ему случайное изображение и посмотреть, какой ярлык он считает своим.

Сначала мы устанавливаем модель в оценочный режим.

 model.eval () 

Затем мы создаем функцию, которая может обрабатывать изображение, чтобы его можно было ввести в нашу модель.

Мы открываем изображение, изменяем его размер, сохраняя соотношение сторон, но сделав самую короткую сторону только 255 пикселей, и обрезаем центр 224 на 224 пикселей. Затем мы превращаем изображение в массив и убеждаемся, что количество цветовых каналов является первым измерением, а не последним, путем транспонирования массива.Затем мы преобразуем каждое значение между 0 и 1 путем деления на 255. Затем мы нормализуем значения путем вычитания среднего и деления на стандартное отклонение. Наконец, мы конвертируем массив в тензор Torch и преобразуем значения в float.

Эти шаги аналогичны шагам, которые мы указали на шаге 2, но на этот раз мы должны вручную кодировать команды, а не полагаться на библиотеку преобразований.

 # Обработать наше изображение 
 def process_image (image_path): 
 # Загрузить изображение 
 img = Image.open (image_path) 
 # Получить размеры изображения 
 width, height = img.size 
 
 # Измените размер, сохранив соотношение сторон, но изменив размер 
 # так, чтобы самый короткий размер был 255px 
 img = img.resize (( 255, int (255 * (высота / ширина))) if width  
 # Получить размеры нового изображения size 
 width, height = img .size 
 
 # Задайте координаты для кадрирования по центру 224 x 224 
 слева = (ширина - 224) / 2 
 сверху = (высота - 224) / 2 
 справа = (ширина + 224) / 2 
 снизу = (рост + 224) / 2 
 img = img.Crop ((слева, вверху, справа, внизу)) 
 
 # Превратить изображение в массив numpy 
 img = np.array (img) 
 
 # Сделать измерение цветового канала первым вместо последнего 
 img = img.transpose ((2 , 0, 1)) 
 
 # Сделать все значения от 0 до 1 
 img = img / 255 
 
 # Нормализовать на основе предварительно установленного среднего и стандартного отклонения 
 img [0] = (img [0] - 0,485) /0,229 
 img [1] = (img [1] - 0,456) /0,224 
 img [2] = (img [2] - 0,406) /0,225 
 
 # Добавьте четвертое измерение в начало, чтобы указать размер пакета 
 img = img [нп.newaxis ,:] 
 
 # Превратить в тензор факела 
 image = torch.from_numpy (img) 
 image = image.float () 
 return image 
 

После обработки изображения мы можем построить функцию, которая будет использовать нашу модель для предсказать этикетку. Мы вводим изображение в нашу модель и получаем результат. Затем мы переворачиваем журнал в функции LogSoftmax, которую мы применили в выходном слое, и возвращаем верхний класс, предсказанный моделью, и степень уверенности в своем предположении.

 # Использование нашей модели для прогнозирования метки 
 def pred (image, model): 
 # Передача изображения через нашу модель 
 output = model.forward (image) 
 # Обратить функцию журнала в нашем выводе 
 output = torch.exp (output) 
 
 # Получить верхний прогнозируемый класс и процент вывода для 
 # этот класс 
 probs, classes = output.topk (1 , dim = 1) 
 return probs.item (), classes.item () 
 

Наконец, мы хотим отобразить изображение. Мы превращаем изображение обратно в массив и ненормализуем его, умножая на стандартное отклонение и добавляя среднее значение. Затем мы используем библиотеку matplotlib.pyplot для построения изображения.

 # Показать изображение 
 def show_image (image): 
 # Преобразовать изображение в numpy 
 image = image.numpy () 
 # Отменить нормализацию изображения 
 image [0] = image [0] * 0,226 + 0,445 
 
 # Распечатайте изображение 
 fig = plt.figure (figsize = (25, 4)) 
 plt.imshow (np.transpose (image [0], (1, 2, 0))) 
 

Теперь мы можем использовать все эти функции, чтобы напечатать предположение нашей модели и насколько оно было достоверным!

 # Образ процесса 
 image = process_image ("root / image1234.jpg") # Предоставить изображение модели для прогнозирования вывода 
 top_prob, top_class = pred (image, model) # Показать изображение 
 show_image (image) # Распечатать результаты 
 print ("Модель есть", top_prob * 100, "% уверенности в том, что изображение имеет предсказанный класс", top_class) 

Вот и все!

compose-spec / spec.md на главном сервере · compose-spec / compose-spec · GitHub

{: .no_toc}

Статус этого документа

Этот документ определяет формат файла Compose, используемый для определения приложений с несколькими контейнерами. Распространение данного документа не ограничено.

Ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ОБЯЗАТЕЛЬНО», «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ДОЛЖЕН», «НЕ ДОЛЖЕН», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и «ДОПОЛНИТЕЛЬНО» должны интерпретироваться, как описано в RFC 2119.

Требования и дополнительные атрибуты

Спецификация Compose включает свойства, предназначенные для локальной среды выполнения контейнера OCI, раскрывая параметры конфигурации ядра Linux, а также некоторые свойства контейнера Windows, а также функции облачной платформы, связанные с размещением ресурсов в кластере, распространением реплицированных приложений и масштабируемостью.

Мы подтверждаем, что никакая реализация Compose не будет поддерживать все атрибуты , и что поддержка некоторых свойств зависит от платформы и может быть подтверждено только во время выполнения. Определение версионной схемы для управления поддерживаемыми свойства в файле Compose, установленном инструментом создания докеров, где компонент Compose формат файла был разработан, не дает никаких гарантий того, что атрибуты конечного пользователя будут фактически реализованы.

Спецификация определяет ожидаемый синтаксис конфигурации и поведение, но - пока не указано иное - поддержка любого из них НЕОБЯЗАТЕЛЬНА.

Реализация Compose для анализа файла Compose с использованием неподдерживаемых атрибутов ДОЛЖНА предупреждать пользователя. Мы рекомендуем разработчиков для поддержки этих режимов работы:

• по умолчанию: предупреждать пользователя о неподдерживаемых атрибутах, но игнорировать их
• strict: предупредить пользователя о неподдерживаемых атрибутах и ​​отклонить файл набора
• свободно: игнорировать неподдерживаемые атрибуты И неизвестные атрибуты (которые не были определены в спецификации на момент создания реализации)

Модель приложения Compose

Спецификация Compose позволяет определить платформенно-независимое контейнерное приложение.Такое приложение разработано как набор контейнеров, которые должны работать вместе с соответствующими общими ресурсами и каналами связи.

Вычислительные компоненты приложения определяются как службы. Служба - это абстрактная концепция, реализованная на платформах путем запуска одного и того же образа контейнера (и конфигурации) один или несколько раз.

взаимодействуют друг с другом через сети. В этой спецификации сеть - это абстракция возможностей платформы для установления IP-маршрута между контейнерами внутри служб, соединенных вместе.Параметры низкоуровневой сети, зависящие от платформы, сгруппированы в определение сети и МОГУТ быть частично реализованы на некоторых платформах.

хранят и передают постоянные данные в тома. Спецификация описывает такие постоянные данные как монтирование файловой системы высокого уровня с глобальными параметрами. Фактические детали реализации, зависящие от платформы, сгруппированы в определение томов и МОГУТ быть частично реализованы на некоторых платформах.

Для некоторых служб требуются данные конфигурации, зависящие от среды выполнения или платформы.Для этого в спецификации определена специальная концепция: Configs. С точки зрения контейнера службы конфигурации сопоставимы с томами в том смысле, что они представляют собой файлы, смонтированные в контейнере. Но фактическое определение включает в себя отдельные ресурсы и службы платформы, которые абстрагируются этим типом.

Секрет - это особая разновидность данных конфигурации для конфиденциальных данных, которую НЕ СЛЕДУЕТ раскрывать без соображений безопасности. Секреты предоставляются службам в виде файлов, смонтированных в их контейнерах, но ресурсы конкретной платформы для предоставления конфиденциальных данных достаточно специфичны, чтобы заслужить отдельную концепцию и определение в спецификации Compose.

Различие в объемах, конфигурациях и секретах позволяет реализациям предлагать сопоставимую абстракцию на уровне обслуживания, но при этом охватывать конкретную конфигурацию адекватных ресурсов платформы для четко идентифицированного использования данных.

A Project - это индивидуальное развертывание спецификации приложения на платформе. Название проекта используется для группировки ресурсы вместе и изолировать их от других приложений или другой установки одного и того же приложения. Составьте указанное приложение с различными параметрами.Реализация Compose, создающая ресурсы на платформе, ДОЛЖНА быть префиксом имен ресурсов по проекту и установите метку com.docker.compose.project .

Иллюстративный пример

Следующий пример иллюстрирует концепцию спецификации Compose на конкретном примере приложения. Пример ненормативный.

Рассмотрим приложение, разделенное на интерфейсное веб-приложение и внутреннюю службу.

Внешний интерфейс настраивается во время выполнения с помощью файла конфигурации HTTP, управляемого инфраструктурой, с предоставлением имени внешнего домена и сертификата сервера HTTPS, введенного защищенным хранилищем секретов платформы.

Серверная часть хранит данные в постоянном томе.

Обе службы взаимодействуют друг с другом в изолированной сети внутреннего уровня, в то время как интерфейс также подключен к сети переднего уровня и предоставляет порт 443 для внешнего использования.

  (Внешний пользователь) -> 443 [внешняя сеть]
                            |
                  + -------------------- +
                  | интерфейсная служба | ... ro ... 
                  | "webapp" |...ro ... <сертификат сервера> #secured
                  + -------------------- +
                            |
                        [серверная сеть]
                            |
                  + -------------------- +
                  | серверная служба | г + ш ___________________
                  | "база данных" | ======= (постоянный том)
                  + -------------------- + \ _________________ /
  

Пример приложения состоит из следующих частей:

• 2 сервиса, поддерживаемые образами Docker: webapp и база данных
• 1 секрет (сертификат HTTPS), внедренный во внешний интерфейс
Конфигурация
• 1 (HTTP), введенная во внешний интерфейс
• 1 постоянный том, прикрепленный к бэкэнду
• 2 сети

 услуги:
  внешний интерфейс:
    изображение: здорово / webapp
    порты:
      - «443: 8043»
    сети:
      - передний ярус
      - задний ярус
    конфиги:
      - httpd-config
    секреты:
      - сервер-сертификат

  бэкэнд:
    изображение: здорово / база данных
    объемы:
      - db-данные: / etc / data
    сети:
      - задний ярус

объемы:
  db-данные:
    драйвер: flocker
    driver_opts:
      размер: «10 ГБ»

конфиги:
  httpd-config:
    внешний: правда

секреты:
  сервер-сертификат:
    внешний: правда

сети:
  # Наличие этих объектов достаточно для их определения
  передний уровень: {}
  задний ярус: {} 

Этот пример иллюстрирует различие между томами, конфигурациями и секретами.Пока все они разоблачены для обслуживания контейнеров как смонтированных файлов или каталогов только том можно настроить для доступа для чтения и записи. Секреты и конфиги доступны только для чтения. Конфигурация тома позволяет вам выбрать драйвер тома и передать параметры драйвера. для настройки управления томами в соответствии с реальной инфраструктурой. Конфиги и секреты полагаются на сервисы платформы, и объявлены внешними , поскольку они не управляются как часть жизненного цикла приложения: реализация Compose будет использовать механизм поиска, зависящий от платформы, для получения значений времени выполнения.

Составить файл

Файл Compose - это файл YAML, определяющий версия (УСТАРЕВШАЯ), услуги (ОБЯЗАТЕЛЬНО), сети, объемы, конфиги и секреты. Путь по умолчанию для файла Compose - compose.yaml (предпочтительно) или compose.yml в рабочем каталоге. Реализации Compose ДОЛЖНЫ также поддерживать docker-compose.yaml и docker-compose.yml для обратной совместимости. Если существуют оба файла, реализации Compose ДОЛЖНЫ предпочесть каноническую компоновку .yaml один.

Файлы Multiple Compose можно объединить вместе для определения модели приложения. Комбинация файлов YAML ДОЛЖЕН быть реализован путем добавления / переопределения элементов YAML на основе порядка файлов Compose, установленного пользователем. Простой Атрибуты и карты заменяются файлом Compose самого высокого порядка, списки объединяются путем добавления. Родственник пути ДОЛЖНЫ быть разрешены на основе первого Compose файла родительской папки, всякий раз, когда дополнительные файлы объединенные размещаются в других папках.

Поскольку некоторые элементы файла Compose могут быть выражены как отдельные строки или сложные объекты, слияние ДОЛЖНО применяться к развернутая форма.

Профили

позволяют настроить модель приложения Compose для различных целей и сред. Составить реализация ДОЛЖНА позволять пользователю определять набор активных профилей. Точный механизм - это реализация специфичен и МОЖЕТ включать флаги командной строки, переменные среды и т.д.

:
  ПОРТ: 8080
  TZ: utc
изображение: busybox 

элементов под blkio_config.device_read_bps , blkio_config.device_read_iops , blkio_config.device_write_bps , blkio_config.device_write_iops , устройства и тома также рассматриваются как сопоставления, где ключ - это целевой путь внутри контейнер.

Например, ввод ниже:

 услуг:
  общий:
    изображение: busybox
    объемы:
      - общий том: / var / lib / backup / data: rw
  cli:
    расширяется:
      сервис: общий
    объемы:
      - cli-volume: / var / lib / backup / data: ro 

Создает следующую конфигурацию для службы cli .Обратите внимание, что смонтированный путь теперь указывает на новое имя тома и был применен флаг ro .

 изображение: busybox
объемы:
- cli-volume: / var / lib / backup / data: ro 

Если , на которое ссылается определение службы , содержит отображение расширяет , элементы под ним просто копируются в новое определение слияния . Затем процесс слияния завершается. снова выключите, пока не перестанет выдвигаться . Осталось ключа.

Например, ввод ниже:

 услуг:
  основание:
    изображение: busybox
    пользователь: root
  общий:
    изображение: busybox
    расширяется:
      услуга: база
  cli:
    расширяется:
      сервис: общий 

Создает следующую конфигурацию для службы cli .Здесь cli services получает пользовательский ключ от общей службы , которая, в свою очередь, получает этот ключ от базы служба.

 изображение: busybox
пользователь: root 

Последовательности

Следующие ключи следует рассматривать как последовательности: cap_add , cap_drop , configs , deploy.placement.constraints , deploy.placement.preferences , deploy.reservations.generic_resources , device_cgroup_rules , expose , external_links , порты , секреты , security_opt .Любые дубликаты, полученные в результате слияния, удаляются, так что только последовательность содержит уникальные элементы.

Например, ввод ниже:

 услуг:
  общий:
    изображение: busybox
    security_opt:
      - метка: роль: РОЛЬ
  cli:
    расширяется:
      сервис: общий
    security_opt:
      - метка: пользователь: USER 

Создает следующую конфигурацию для службы cli .

 изображение: busybox
security_opt:
- метка: роль: РОЛЬ
- метка: пользователь: USER 

В случае использования синтаксиса списка следующие ключи также следует рассматривать как последовательности: dns , dns_search , env_file , tmpfs .В отличие от полей последовательности, упомянутых выше, дубликаты, полученные в результате слияния, не удаляются.

Скаляры

Любые другие разрешенные ключи в определении службы следует рассматривать как скаляры.

external_links

external_links связывает служебные контейнеры со службами, управляемыми вне этого приложения Compose. external_links определяет имя существующей службы для извлечения с использованием механизма поиска платформы. Можно указать псевдоним в форме СЕРВИС: АЛИАС .

 внешних_ссылок:
  - Redis
  - база данных: mysql
  - база данных: postgresql 

extra_hosts

extra_hosts добавляет сопоставления имен хостов в конфигурацию сетевого интерфейса контейнера ( / etc / hosts для Linux). Значения ДОЛЖНЫ устанавливать имя хоста и IP-адрес для дополнительных хостов в виде ИМЯ ХОСТА: IP .

 extra_hosts:
  - "somehost: 162.242.195.82"
  - "otherhost: 50.31.209.229" 

Compose ДОЛЖНЫ создавать соответствующую запись с IP-адресом и именем хоста в сети контейнера. конфигурации, что означает, что для Linux / etc / hosts получит дополнительные строки:

  162.242.195.82 somehost
50.31.209.229 другой хост
  

group_add

group_add определяет дополнительные группы (по имени или номеру), членом которых ДОЛЖЕН быть пользователь внутри контейнера.

Пример того, где это полезно, - когда несколько контейнеров (работающих как разные пользователи) должны все читать или писать тот же файл на общем томе. Этот файл может принадлежать группе, совместно используемой всеми контейнерами, и указанной в group_add .

 услуг:
  myservice:
    изображение: альпийский
    group_add:
      - почта 

Запуск id внутри созданного контейнера ДОЛЖЕН показывать, что пользователь принадлежит к группе mail , которая не будет иметь имело место, если не было объявлено group_add .

проверка работоспособности

healthcheck объявляет проверку, которая запускается, чтобы определить, есть ли контейнеры для этого сервис "здоровый". Это отменяет Инструкция HEALTHCHECK Dockerfile устанавливается Docker-образом службы.

 проверка работоспособности:
  test: ["CMD", "curl", "-f", "http: // localhost"]
  интервал: 1 мин 30 сек
  тайм-аут: 10 с
  повторных попыток: 3
  start_period: 40 с 

интервал , тайм-аут и start_period указаны как длительности.

test определяет команду, которую реализация Compose будет запускать для проверки работоспособности контейнера. Может быть либо строка, либо список. Если это список, первый элемент должен быть NONE , CMD или CMD-SHELL . Если это строка, это эквивалентно указанию CMD-SHELL , за которым следует эта строка.

 # Нажмите на локальное веб-приложение
тест: ["CMD", "curl", "-f", "http: // localhost"] 

Использование CMD-SHELL запустит команду, сконфигурированную как строку, используя оболочку контейнера по умолчанию. ( / bin / sh для Linux).Обе формы ниже эквивалентны:

 тест: ["CMD-SHELL", "curl -f http: // localhost || exit 1"] 

 тест: curl -f https: // localhost || выход 1 

НЕТ отключает проверку работоспособности и в основном полезен для отключения проверки работоспособности, установленной образом. Альтернативно проверку работоспособности, установленную изображением, можно отключить, установив disable: true :

 проверка работоспособности:
  отключить: true 

имя хоста

hostname объявляет настраиваемое имя хоста для использования в сервисном контейнере.ДОЛЖНО быть допустимым именем хоста RFC 1123.

изображение

image указывает образ, с которого будет запускаться контейнер. Изображение ДОЛЖНО соответствовать спецификации открытого контейнера адресный формат изображения, как [ /] [ /] [: | @ ] .

 изображение: redis
    изображение: redis: 5
    изображение: redis @ sha356: 0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83
8bc4b991aac7
    изображение: библиотека / redis
    изображение: docker.io/library/redis
    изображение: my_private.реестр: 5000 / redis 

Если изображение не существует на платформе, реализации Compose ДОЛЖНЫ попытаться извлечь его на основе pull_policy . Реализации Compose с поддержкой сборки МОГУТ предлагать конечному пользователю альтернативные варианты управления приоритетом потянуть за создание изображения из источника, однако вытягивание изображения ДОЛЖНО быть поведением по умолчанию.

изображение МОЖЕТ быть опущено в файле Compose, если объявлен раздел build .Составьте реализации без поддержки сборки НЕОБХОДИМО завершиться ошибкой, если изображение отсутствует в файле Compose.

инициализации

init запускает процесс init (PID 1) внутри контейнера, который пересылает сигналы и пересылает процессы. Установите для этого параметра значение true , чтобы включить эту функцию для службы.

 услуг:
  Интернет:
    изображение: альпийский: последний
    init: true 

Используемый двоичный файл инициализации зависит от платформы.

ipc

ipc настраивает режим изоляции IPC, установленный сервисным контейнером.Имеется в наличии значения зависят от платформы, но спецификация Compose определяет конкретные значения которые ДОЛЖНЫ быть реализованы, как описано, если поддерживается:

• разделяемый , который дает контейнеру собственное частное пространство имен IPC с возможность поделиться им с другими контейнерами.
• услуга: {name} , которая объединяет контейнер с другим ( разделяемый ) пространство имен IPC контейнера.

 IPC: «общий»
    ipc: "служба: [название службы]" 

изоляция

изоляция определяет технологию изоляции контейнера.Поддерживаемые значения зависят от платформы.

этикеток

метки добавляют метаданные в контейнеры. Вы можете использовать массив или карту.

Рекомендуется использовать нотацию обратного DNS, чтобы ваши метки не конфликтовали с те, которые используются другим программным обеспечением.

 этикеток:
  com.example.description: "Веб-приложение для бухгалтерского учета"
  com.example.department: «Финансы»
  com.example.label-with-empty-value: "" 

 этикеток:
  - "com.example.description = Бухгалтерское веб-приложение"
  - «ком.example.department = Финансы "
  - "com.example.label-with-empty-value" 

Реализации Compose ДОЛЖНЫ создавать контейнеры с каноническими метками:

• com.docker.compose.project установить для всех ресурсов, созданных реализацией Compose, для имени проекта пользователя
• com.docker.compose.service , установленный в контейнерах служб с именем службы, как определено в файле Compose

Префикс метки com.docker.compose зарезервирован.Указание меток с этим префиксом в файле Compose ДОЛЖНО приведет к ошибке выполнения.

ссылок

ссылки определяет сетевую ссылку на контейнеры в другой службе. Либо укажите имя службы и псевдоним ссылки ( SERVICE: ALIAS ) или просто имя службы.

 Интернет:
  ссылки:
    - дб
    - db: база данных
    - Redis 

Контейнеры для связанной службы ДОЛЖНЫ быть доступны на имени хоста, идентичном псевдониму, или имени службы. если не указан псевдоним.

Ссылки не требуются для того, чтобы службы могли обмениваться данными - когда не задана конкретная конфигурация сети, любая служба ДОЛЖНА иметь доступ к любой другой службе с именем этой службы в сети по умолчанию . Если услуги объявляют сети, к которым они подключены, ссылки НЕ ДОЛЖНЫ переопределять конфигурацию сети, а службы не подключенный к общей сети, НЕ ДОЛЖЕН иметь возможность общаться. Реализации Compose НЕ МОГУТ предупреждать пользователя об этом несоответствии конфигурации.

Ссылки также выражают неявную зависимость между службами так же, как зависимости_on, поэтому они определяют порядок запуска службы.

лесозаготовка

ведение журнала определяет конфигурацию ведения журнала для службы.

 регистрация:
  драйвер: системный журнал
  опции:
    адрес системного журнала: "tcp: //192.168.0.42: 123" 

Драйвер Имя определяет драйвер ведения журнала для контейнеров службы. Значения по умолчанию и доступные значения зависят от платформы.Параметры драйвера могут быть установлены с помощью параметров в виде пар ключ-значение.

network_mode

network_mode установить сетевой режим служебных контейнеров. Доступные значения зависят от платформы, но Compose Спецификация определяет конкретные значения, которые ДОЛЖНЫ быть реализованы, как описано, если поддерживается:

• нет , которые отключают все сети контейнеров
• хост , который предоставляет контейнеру необработанный доступ к сетевому интерфейсу хоста
• служба: {name} , которая дает контейнерам доступ только к указанной службе

 network_mode: "хост"
    network_mode: "нет"
    network_mode: "service: [название службы]" 

сетей

сети определяет сети, к которым подключены сервисные контейнеры, ссылаясь на записи в сети верхнего уровня ключ.

 услуг:
  какой-то сервис:
    сети:
      - какая-то сеть
      - другие сети 

псевдонимов

aliases объявляет альтернативные имена хостов для этой службы в сети. Другие контейнеры на том же network может использовать имя службы или этот псевдоним для подключения к одному из контейнеров службы.

Поскольку псевдонимы относятся к сети, одна и та же служба может иметь разные псевдонимы в разных сетях.

Примечание : Псевдоним в масштабе всей сети может использоваться несколькими контейнерами и даже несколькими службами.Если это так, то не гарантируется, в какой именно контейнер разрешается имя.

Здесь показан общий формат:

 услуг:
  какой-то сервис:
    сети:
      какая-то сеть:
        псевдонимы:
          - псевдоним1
          - псевдоним3
      другая-сеть:
        псевдонимы:
          - псевдоним 2 

: osx
платформа: windows / amd64
платформа: linux / arm64 / v8 

портов

Открывает контейнерные порты. Отображение портов НЕ ДОЛЖНО использоваться с network_mode: host , и это ДОЛЖНО привести к ошибке времени выполнения.

Краткий синтаксис

Короткий синтаксис - это разделенная запятыми строка для установки IP-адреса хоста, порта хоста и порта контейнера. по форме:

[HOST:] CONTAINER [/ PROTOCOL] где:

• HOST - это [IP:] (порт | диапазон)
• КОНТЕЙНЕР порт | диапазон
• ПРОТОКОЛ для ограничения порта указанным протоколом. tcp и udp значения определены в спецификации, Реализации Compose МОГУТ предлагать поддержку имен протоколов, зависящих от платформы.

IP-адрес хоста, если не установлен, ДОЛЖЕН быть привязан ко всем сетевым интерфейсам. Порт может быть как одиночным значение или диапазон. Хост и контейнер ДОЛЖНЫ использовать эквивалентные диапазоны.

Укажите оба порта ( HOST: CONTAINER ) или только порт контейнера. В последнем случае Реализация Compose ДОЛЖНА автоматически выделять любой неназначенный порт хоста.

HOST: CONTAINER ДОЛЖЕН всегда указываться как строка (заключенная в кавычки), чтобы избежать конфликтов. с поплавком ямл base-60.

Образцов:

 портов:
  - «3000»
  - «3000-3005»
  - «8000: 8000»
  - «9090-9091: 8080-8081»
  - «49100: 22»
  - «127.0.0.1:8001:8001»
  - «127.0.0.1:5000-5010:5000-5010»
  - «6060: 6060 / udp» 

Примечание : Сопоставление IP-адресов хоста МОЖЕТ не поддерживаться на платформе, в таком случае реализации Compose СЛЕДУЕТ отклонять файл Compose и ДОЛЖЕН сообщить пользователю, что он проигнорирует указанный IP-адрес хоста.

Длинный синтаксис

Синтаксис полной формы позволяет настраивать дополнительные поля, которые не могут быть выражается в краткой форме.

• цель : контейнерный порт
• опубликовано : публично открытый порт
• host_ip : неуказанное сопоставление IP-адресов хоста означает все сетевые интерфейсы ( 0.0.0.0 )
• протокол : протокол порта ( tcp или udp ), неуказанный означает любой протокол
• режим : хост для публикации порта хоста на каждом узле или вход для порта для балансировки нагрузки.

 портов:
  - Цель: 80
    host_ip: 127.0.0.1
    опубликовано: 8080
    протокол: tcp
    режим: хост 

привилегированный

с привилегиями настраивает контейнер службы для работы с повышенными привилегиями. Поддержка и фактическое воздействие зависят от платформы.

профилей

профилей определяет список именованных профилей для службы, которая будет включена. Если не установлен, служба всегда включена.

Если присутствует, профиль ДОЛЖЕН следовать формату регулярного выражения [a-zA-Z0-9] [a-zA-Z0-9_.-] + .

pull_policy

pull_policy определяет решения, которые будут принимать реализации Compose, когда они начинают извлекать изображения. Возможные значения:

• всегда : реализации Compose ДОЛЖНЫ всегда извлекать образ из реестра.
• никогда. : реализации Compose НЕ ДОЛЖНЫ извлекать образ из реестра и ДОЛЖНЫ полагаться на кэшированный образ платформы. Если кэшированного изображения нет, НЕОБХОДИМО сообщить об ошибке.
• отсутствует : реализациям Compose СЛЕДУЕТ извлекать изображение только в том случае, если оно недоступно в кэше платформы. Это ДОЛЖНО быть опцией по умолчанию для реализаций Compose без поддержки сборки. if_not_present СЛЕДУЕТ рассматривать как псевдоним для этого значения для обратной совместимости
• build : реализации Compose ДОЛЖНЫ создавать образ. Реализации Compose ДОЛЖНЫ перестраивать образ, если он уже присутствует.

Если присутствуют pull_policy и build , реализациям Compose СЛЕДУЕТ строить образ по умолчанию.Реализации Compose МОГУТ переопределить это поведение в цепочке инструментов.

только чтение

read_only настраивает создание контейнера службы с файловой системой, доступной только для чтения.

перезапуск

перезапуск определяет политику, которую платформа будет применять при завершении работы контейнера.

• нет : Политика перезапуска по умолчанию. Не перезапускает контейнер ни при каких обстоятельствах.
• всегда : политика всегда перезапускает контейнер до его удаления.
• при сбое : политика перезапускает контейнер, если код выхода указывает на ошибку.
• без остановки : политика перезапускает контейнер независимо от кода выхода, но останавливается перезапуск при остановке или удалении службы.

 перезапуск: «нет»
    перезапуск: всегда
    перезапуск: при сбое
    перезапуск: если не остановлен 

время выполнения

среда выполнения указывает, какую среду выполнения использовать для контейнеров службы.

Значение время выполнения зависит от реализации. Например, среда выполнения может быть именем реализации спецификации времени выполнения OCI, например runc.

 Интернет:
  изображение: busybox: последний
  команда: true
  время выполнения: runc 

масштаб

-УСТАРЕЛО: используйте deploy / replicas_

Масштаб указывает количество контейнеров по умолчанию для развертывания для этой службы.

секретов

секретов предоставляет доступ к конфиденциальным данным, определяемым секретами, для каждой услуги.Два поддерживаются различные варианты синтаксиса: короткий синтаксис и длинный синтаксис.

Compose ДОЛЖНЫ сообщать об ошибке, если секрет не существует на платформе или не определен в секреты раздела этого файла Compose.

Краткий синтаксис

В сокращенном варианте синтаксиса указывается только секретное имя. Это дает доступ контейнера к секрету и монтирует его как доступный только для чтения в / run / secrets / внутри контейнера.Устанавливаются как имя источника, так и конечная точка монтирования. к секретному имени.

Compose ДОЛЖНЫ устанавливать метки com.docker.compose.project и com.docker.compose.network .

внешний

Если установлено значение true , external указывает, что жизненный цикл этой сети поддерживается вне жизненного цикла приложения. Реализациям Compose НЕ СЛЕДУЕТ пытаться создать эти сети и выдает ошибку, если таковая не существует.

В приведенном ниже примере прокси-сервер является шлюзом во внешний мир.Вместо того, чтобы пытаться создать сеть, напишите реализации ДОЛЖНЫ опрашивать платформу для существующей сети, просто называемой вне , и подключать проксирует к нему контейнеры сервиса .

 услуг:
  прокси:
    изображение: здорово / прокси
    сети:
      - за пределами
      - дефолт
  приложение:
    изображение: здорово / приложение
    сети:
      - дефолт

сети:
  за пределами:
    внешний: истинный 

название

имя устанавливает собственное имя для этой сети.Поле имени может использоваться для ссылки на сети, содержащие специальные символы. Имя используется как есть, и область действия , а не будет ограничена именем проекта.

 сетей:
  сеть1:
    имя: my-app-net 

Его также можно использовать вместе со свойством external для определения сети платформы, которую реализация Compose должен извлекаться, как правило, с использованием параметра, поэтому в файле Compose не требуется жестко запрограммировать конкретные значения времени выполнения:

 сетей:
  сеть1:
    внешний: правда
    имя: "$ {NETWORK_ID}" 

Объемный элемент верхнего уровня

Тома - это постоянные хранилища данных, реализованные платформой.Спецификация Compose предлагает нейтральную абстракцию для служб для монтирования томов и параметров конфигурации для их размещения в инфраструктуре.

Раздел тома позволяет конфигурировать именованные тома, которые можно повторно использовать в нескольких службах. Вот пример настройки с двумя службами, где каталог данных базы данных используется совместно с другой службой в качестве тома, поэтому что его можно периодически создавать резервные копии:

 услуг:
  бэкэнд:
    изображение: здорово / база данных
    объемы:
      - db-данные: / etc / data

  резервное копирование:
    изображение: служба резервного копирования
    объемы:
      - данные базы данных: / var / lib / backup / data

объемы:
  db-данные: 

Запись под ключом томов верхнего уровня может быть пустой, и в этом случае она использует конфигурацию платформы по умолчанию для создание объема.При желании вы можете настроить его с помощью следующих ключей:

драйвер

Укажите, какой драйвер тома следует использовать для этого тома. Значения по умолчанию и доступные значения зависят от платформы. Если драйвер недоступен, реализация Compose ДОЛЖНА вернуть ошибку и остановить развертывание приложения.

driver_opts

driver_opts определяет список параметров в виде пар "ключ-значение" для передачи драйверу для этого тома. Эти параметры зависят от драйвера.

 томов:
  пример:
    driver_opts:
      тип: "nfs"
      o: "addr = 10.40.0.199, nolock, soft, rw"
      устройство: ": / docker / example" 

внешний

Если установлено значение true , external указывает, что этот том уже существует на платформе и его жизненный цикл управляется извне. из приложения. Реализации Compose НЕ ДОЛЖНЫ пытаться создать эти тома и ДОЛЖНЫ возвращать ошибку, если они не существует.

В приведенном ниже примере вместо попытки создать том с именем {project_name} _data , Compose просто ищет существующий том называется data и монтирует его в сервисные контейнеры db .

 услуг:
  бэкэнд:
    изображение: здорово / база данных
    объемы:
      - db-данные: / etc / data

объемы:
  db-данные:
    внешний: истинный 

этикеток

метки используются для добавления метаданных к томам. Вы можете использовать массив или словарь.

Рекомендуется использовать обратную нотацию DNS, чтобы ваши метки не противоречащие тем, которые используются другим программным обеспечением.

 этикеток:
  com.example.description: «Объем базы данных»
  com.example.отдел: «IT / Ops»
  com.example.label-with-empty-value: "" 

 этикеток:
  - "com.example.description = Объем базы данных"
  - "com.example.department = IT / Ops"
  - "com.example.label-with-empty-value" 

Compose ДОЛЖНА установить метки com.docker.compose.project и com.docker.compose.volume .

название

имя задает собственное имя для этого тома. Поле имени можно использовать для ссылки на тома, которые содержат специальные персонажи.Имя используется как есть, и область , а не будет ограничена именем стека.

 томов:
  данные:
    name: "my-app-data" 

Его также можно использовать вместе с внешним свойством . При этом имя тома, которое использовалось для поиска фактический объем на платформе устанавливается отдельно от имени, используемого для ссылки на него в файле Compose:

 томов:
  db-данные:
    внешний:
      имя: фактическое-имя-тома 

Это позволяет сделать это имя поиска параметром файла Compose, так что идентификатор модели для тома жестко запрограммирован, но фактический идентификатор тома на платформе устанавливается во время выполнения во время развертывания:

 томов:
  db-данные:
    внешний:
      имя: $ {DATABASE_VOLUME} 

Конфигурация элемента верхнего уровня

позволяют службам адаптировать свое поведение без необходимости перестраивать образ Docker.Конфигурации сопоставимы с томами с точки зрения обслуживания, поскольку они монтируются в файловую систему контейнеров службы. Фактические детали реализации для получения конфигурации, предоставляемой платформой, могут быть установлены из определения конфигурации.

При предоставлении доступа к конфигурации содержимое конфигурации монтируется как файл в контейнере. Местоположение точки монтирования в контейнере по умолчанию - / в контейнерах Linux и C: \ в контейнерах Windows.

По умолчанию, конфигурация ДОЛЖНА принадлежать пользователю, выполняющему команду контейнера, но может быть переопределена конфигурацией службы. По умолчанию конфигурация ДОЛЖНА иметь права доступа для чтения всем (режим 0444), если только служба не настроена для переопределения этого.

могут получить доступ к конфигурациям только в том случае, если это явно предоставлено подразделом config .

Конфиги верхнего уровня , декларация определяет или ссылается данные конфигурации, которые могут быть предоставлены службам в этом применение.Источником конфигурации является либо файл , либо внешний .

• файл : Конфигурация создается с содержимым файла по указанному пути.
• external : Если установлено значение true, указывает, что эта конфигурация уже была создана. Compose реализация не пытается создать его, и если он не существует, возникает ошибка.
• имя : Имя объекта конфигурации на платформе для поиска. Это поле можно использовать для справочные конфигурации, содержащие специальные символы.Имя используется как есть и область действия , а не будет ограничена именем проекта.

В этом примере создается http_config (как _http_config ) при развертывании приложения, и my_second_config ДОЛЖЕН уже существовать на платформе, и значение будет получено путем поиска.

В этом примере server-http_config создается как _http_config при развертывании приложения, зарегистрировав содержимое файла httpd.conf как данные конфигурации.

:
  http_config:
    файл: ./httpd.conf 

В качестве альтернативы, http_config можно объявить как внешний, при этом реализация Compose будет искать server-certificate , чтобы предоставить данные конфигурации соответствующим службам.

:
  http_config:
    внешний: истинный 

Поиск внешних конфигураций также может использовать отдельный ключ, указав имя . Следующие Пример изменяет предыдущий для поиска конфигурации с помощью параметра HTTP_CONFIG_KEY .Делает поэтому фактический ключ поиска будет установлен во время развертывания путем интерполяции переменные, но доступны контейнерам как жестко запрограммированный ID http_config .

:
  http_config:
    внешний: правда
    имя: "$ {HTTP_CONFIG_KEY}" 

Файл Compose должен явно предоставлять доступ к конфигурациям для соответствующих служб в приложении.

Секреты элемента верхнего уровня

Secrets - это разновидность конфигураций, ориентированных на конфиденциальные данные, с определенными ограничениями для этого использования.Поскольку реализация платформы может существенно отличаться от конфигураций, специальный раздел Секреты позволяет настроить соответствующие ресурсы.

Объявление секретов верхнего уровня определяет или ссылается на конфиденциальные данные, которые могут быть предоставлены службам в этом применение. Источником секрета является либо файл , либо внешний .

• файл : секрет создается из содержимого файла по указанному пути.
• external : Если установлено значение true, указывает, что этот секрет уже был создан.Реализация Compose делает не пытайтесь создать его, и если он не существует, возникает ошибка.
• имя : Имя секретного объекта в Docker. Это поле можно использовать для ссылочные секреты, содержащие специальные символы. Имя используется как есть и область действия , а не будет ограничена именем проекта.

В этом примере server-certificate создается как _server-certificate при развертывании приложения, путем регистрации содержимого сервера .cert как секрет платформы.

 секретов:
  сервер-сертификат:
    файл: ./server.cert 

В качестве альтернативы, server-certificate может быть объявлен как внешний, при этом реализация Compose будет искать server-certificate , чтобы раскрыть секрет для соответствующих служб.

 секретов:
  сервер-сертификат:
    внешний: истинный 

Поиск внешних секретов также может использовать отдельный ключ, указав имя . Следующие Пример изменяет предыдущий для поиска секрета с помощью параметра CERTIFICATE_KEY .Делает поэтому фактический ключ поиска будет установлен во время развертывания путем интерполяции переменные, но доступны контейнерам как жестко запрограммированный ID server-certificate .

 секретов:
  сервер-сертификат:
    внешний: правда
    имя: "$ {CERTIFICATE_KEY}" 

Файл Compose должен явно предоставлять доступ к секретам для соответствующих служб в приложении.

Фрагменты

Можно повторно использовать фрагменты конфигурации с помощью якорей YAML.

 томов:
  db-data: & объем по умолчанию
    драйвер: по умолчанию
  метрики: * объем по умолчанию 

В предыдущем примере привязка создана как объем по умолчанию на основе спецификации объема db-data .Позже он повторно используется псевдонимом * default-volume для определения метрики volume. Та же логика может применяться к любому элементу в файле Compose. Разрешение привязки ДОЛЖНО иметь место перед интерполяцией переменных, поэтому переменные нельзя использовать для установки якорей или псевдонимов.

Также возможно частично переопределить значения, установленные ссылкой привязки, с помощью Тип слияния YAML. В следующем примере для метрики в спецификации объема используется псевдоним. чтобы избежать повторения, но переопределить имя атрибут:

 услуг:
  бэкэнд:
    изображение: здорово / база данных
    объемы:
      - db-данные
      - метрики
объемы:
  db-data: & объем по умолчанию
    драйвер: по умолчанию
    имя: "данные"
  метрики:
    <<: * объем по умолчанию
    имя: "метрики" 

Добавочный номер

Специальные поля расширения могут иметь любой формат, если их имя начинается с последовательности символов x- .Их можно использовать внутри любой структуры в файле Compose. Это единственное исключение для реализаций Compose, которые молча игнорируют нераспознанное поле.

 x-обычай:
  foo:
    - бар
    - зот

Сервисы:
  webapp:
    изображение: здорово / webapp
    x-foo: бар 

Содержимое таких полей не определено спецификацией Compose и может использоваться для включения настраиваемых функций. Реализация Compose для обнаружения неизвестного поля расширения НЕ ДОЛЖНА давать сбой, но МОЖЕТ предупреждать о неизвестном поле.

Для расширений платформы настоятельно рекомендуется использовать префикс расширения по имени платформы / поставщика, точно так же, как браузеры добавляют поддержка пользовательских функций CSS

 сервис:
  бэкэнд:
    развертывать:
      размещение:
        x-aws-role: "arn: aws: iam :: XXXXXXXXXXXX: role / foo"
        x-aws-region: "ес-запад-3"
        x-azure-region: "france-central" 

Информационные исторические записки

Этот раздел носит информативный характер. На момент написания были известны следующие префиксы:

Использование расширений как фрагментов

С поддержкой полей расширения файл Compose можно записать следующим образом, чтобы улучшить читаемость повторно используемых фрагментов:

 x-logging: & default-logging
  опции:
    макс-размер: «12 м»
    max-файл: "5"
  драйвер: json-файл

Сервисы:
  внешний интерфейс:
    изображение: здорово / webapp
    ведение журнала: * ведение журнала по умолчанию
  бэкэнд:
    изображение: здорово / база данных
    ведение журнала: * ведение журнала по умолчанию 

с указанием байтовых значений

Значение представляет байтовое значение в виде строки в формате {количество} {байтовая единица} : Поддерживаемые единицы: b (байты), k или kb (килобайты), m или mb (мегабайты) и g или gb (гигабайты).

с указанием продолжительности

Значение выражает продолжительность в виде строки в форме {значение} {единица} . Поддерживаемые единицы: мкс, (микросекунды), мс, (миллисекунды), с, (секунды), м, (минуты) и ч, (часы). Значение может объединять несколько значений и использовать без разделителя.

  10 мс
  40-е годы
  1 мин. 30 сек.
  1ч5м30с20мс
  

Интерполяция

Значения в файле Compose могут быть заданы переменными и интерполированы во время выполнения.Создавайте файлы, используя Bash-подобный синтаксис $ {VARIABLE}

Поддерживаются синтаксисы $ VARIABLE и $ {VARIABLE} . Значения по умолчанию могут быть определены в строке с использованием типичного синтаксиса оболочки: последний

• $ {VARIABLE: -default} оценивается как по умолчанию , если VARIABLE не задано или пустой в окружающей среде.
• $ {VARIABLE-default} оценивается как по умолчанию , только если VARIABLE не задано в окружающей среде.

Аналогичным образом следующий синтаксис позволяет указать обязательные переменные:

• $ {VARIABLE:? Err} выходит с сообщением об ошибке, содержащим err , если ПЕРЕМЕННАЯ не задана или пуста в среде.
• $ {VARIABLE? Err} завершается с сообщением об ошибке, содержащим err , если ПЕРЕМЕННАЯ не задана в среде.

Другие расширенные функции в стиле оболочки, такие как $ {VARIABLE / foo / bar} , не поддерживаются. поддерживается спецификацией Compose.

Вы можете использовать $$ (знак двойного доллара), когда вашей конфигурации нужен буквальный знак доллара. Это также не позволяет Compose интерполировать значение, поэтому $$ позволяет вам обращаться к переменным среды, которые вы не хотите обрабатывать Сочинять.

 Интернет:
  строить: .
  команда: "$$ VAR_NOT_INTERPOLATED_BY_COMPOSE" 

Если реализация Compose не может разрешить замененную переменную и значение по умолчанию не определено, она ДОЛЖНА предупредить пользователя и замените переменную пустой строкой.

Поскольку любые значения в файле Compose могут быть интерполированы с заменой переменных, включая компактную строковую нотацию для сложных элементов ДОЛЖНА применяться интерполяция перед слиянием для каждого файла.