swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: 'Microsoft Azure AccessControlClient AccessConnector Fine-Tuning: API'
schemes:
- https
tags:
- name: 'Fine-Tuning:'
paths:
  /fine_tuning/jobs:
    get:
      tags:
      - 'Fine-Tuning:'
      summary: "Microsoft Azure Gets A List Of All Fine Tune Jobs Owned By The Azure Openai Resource \r\nthe Details That Are Returned For Each Fine Tune Job Contain Besides Its Identifier\r\nthe Base Model, Training And Validation Files, Hyper Parameters, Time Stamps, Status And Events \r\nevents Are Created When The Job Status Changes, E G Running Or Complete, And When Results Are Uploaded"
      operationId: microsoftAzureFinetuningList
      produces:
      - application/json
      parameters:
      - in: query
        name: after
        description: Identifier for the last event from the previous pagination request.
        type: string
      - in: query
        name: limit
        description: Number of events to retrieve. Defaults to 20.
        type: integer
        format: int32
        default: 20
      - $ref: '#/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/FineTuningJobList'
        default:
          description: An error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Getting all fine tune jobs owned by this account.:
          $ref: ./examples/get_finetuning_jobs.json
      description: Needs a more full description created.
    post:
      tags:
      - 'Fine-Tuning:'
      summary: "Microsoft Azure Creates A Job That Fine Tunes A Specified Model From A Given Training File \r\nresponse Includes Details Of The Enqueued Job Including Job Status And Hyper Parameters \r\nthe Name Of The Fine Tuned Model Is Added To The Response Once Complete"
      operationId: microsoftAzureFinetuningCreate
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/apiVersionQueryParameter'
      - in: body
        name: fineTuningJob
        description: "The specification of the fine-tuned model to create.\r\nRequired parameters are the base model and the training file to use.\r\nOptionally a validation file can be specified to compute validation metrics during training.\r\nHyper parameters will be set to default values or can by optionally specified.\r\nThese include batch size, learning rate multiplier, number of epochs and others."
        required: true
        schema:
          $ref: '#/definitions/FineTuningJobCreation'
      responses:
        '201':
          description: The fine tune has been successfully created.
          schema:
            $ref: '#/definitions/FineTuningJob'
          headers:
            Location:
              description: The location of the newly created item.
              type: string
              format: url
        default:
          description: An error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Creating a fine tune job.:
          $ref: ./examples/post_finetuning_job.json
      description: Needs a more full description created.
  /fine_tuning/jobs/{fine-tuning-job-id}:
    get:
      tags:
      - 'Fine-Tuning:'
      summary: "Microsoft Azure Gets Details For A Single Fine Tune Job Specified By The Given Fine Tune Id \r\nthe Details Contain The Base Model, Training And Validation Files, Hyper Parameters, Time Stamps, Status And Events \r\nevents Are Created When The Job Status Changes, E G Running Or Complete, And When Results Are Uploaded"
      operationId: microsoftAzureFinetuningGet
      produces:
      - application/json
      parameters:
      - in: path
        name: fine-tuning-job-id
        description: The identifier of the fine-tune job.
        required: true
        type: string
      - $ref: '#/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/FineTuningJob'
        default:
          description: An error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Getting a fine tune job.:
          $ref: ./examples/get_finetuning_job.json
      description: Needs a more full description created.
    delete:
      tags:
      - 'Fine-Tuning:'
      summary: Microsoft Azure Deletes The Fine Tune Job Specified By The Given Fine Tune Id
      operationId: microsoftAzureFinetuningDelete
      produces:
      - application/json
      parameters:
      - in: path
        name: fine-tuning-job-id
        description: The identifier of the fine-tune job.
        required: true
        type: string
      - $ref: '#/parameters/apiVersionQueryParameter'
      responses:
        '204':
          description: The fine tune was successfully deleted.
        default:
          description: An error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Deleting a fine tune job.:
          $ref: ./examples/delete_finetuning_job.json
      description: Needs a more full description created.
  /fine_tuning/jobs/{fine-tuning-job-id}/events:
    get:
      tags:
      - 'Fine-Tuning:'
      summary: "Microsoft Azure Gets The Events For The Fine Tune Job Specified By The Given Fine Tune Id \r\nevents Are Created When The Job Status Changes, E G Running Or Complete, And When Results Are Uploaded"
      operationId: microsoftAzureFinetuningGetevents
      produces:
      - application/json
      parameters:
      - in: path
        name: fine-tuning-job-id
        description: The identifier of the fine-tune job.
        required: true
        type: string
      - in: query
        name: after
        description: Identifier for the last event from the previous pagination request.
        type: string
      - in: query
        name: limit
        description: Number of events to retrieve. Defaults to 20.
        type: integer
        format: int32
        default: 20
      - $ref: '#/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/FineTuningJobEventList'
        default:
          description: An error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Getting events of a fine tune job.:
          $ref: ./examples/get_finetuning_job_events.json
      description: Needs a more full description created.
  /fine_tuning/jobs/{fine-tuning-job-id}/cancel:
    post:
      tags:
      - 'Fine-Tuning:'
      summary: Microsoft Azure Cancels The Processing Of The Fine Tune Job Specified By The Given Fine Tune Id
      operationId: microsoftAzureFinetuningCancel
      produces:
      - application/json
      parameters:
      - in: path
        name: fine-tuning-job-id
        description: The identifier of the fine-tune job.
        required: true
        type: string
      - $ref: '#/parameters/apiVersionQueryParameter'
      responses:
        '200':
          description: The fine tune has been successfully canceled
          schema:
            $ref: '#/definitions/FineTuningJob'
        default:
          description: An error occurred.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Canceling a fine tune job.:
          $ref: ./examples/cancel_finetuning_job.json
      description: Needs a more full description created.
definitions:
  ErrorResponse:
    title: ErrorResponse
    description: "Error response as defined in the Microsoft REST guidelines\r\n(https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses)."
    required:
    - error
    type: object
    properties:
      error:
        $ref: '#/definitions/Error'
  ErrorCode:
    title: ErrorCode
    description: "Error codes as defined in the Microsoft REST guidelines\r\n(https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses)."
    enum:
    - conflict
    - invalidPayload
    - forbidden
    - notFound
    - unexpectedEntityState
    - itemDoesAlreadyExist
    - serviceUnavailable
    - internalFailure
    - quotaExceeded
    - jsonlValidationFailed
    - fileImportFailed
    - tooManyRequests
    - unauthorized
    - contentFilter
    type: string
    x-ms-enum:
      name: ErrorCode
      modelAsString: true
      values:
      - value: conflict
        description: The requested operation conflicts with the current resource state.
      - value: invalidPayload
        description: The request data is invalid for this operation.
      - value: forbidden
        description: The operation is forbidden for the current user/api key.
      - value: notFound
        description: The resource is not found.
      - value: unexpectedEntityState
        description: The operation cannot be executed in the current resource's state.
      - value: itemDoesAlreadyExist
        description: The item does already exist.
      - value: serviceUnavailable
        description: The service is currently not available.
      - value: internalFailure
        description: Internal error. Please retry.
      - value: quotaExceeded
        description: Quota exceeded.
      - value: jsonlValidationFailed
        description: Validation of jsonl data failed.
      - value: fileImportFailed
        description: Import of file failed.
      - value: tooManyRequests
        description: Too many requests. Please retry later.
      - value: unauthorized
        description: The current user/api key is not authorized for the operation.
      - value: contentFilter
        description: Image generation failed as a result of our safety system.
  TypeDiscriminator:
    title: TypeDiscriminator
    description: Defines the type of an object.
    enum:
    - list
    - fine-tune
    - fine_tuning.job
    - file
    - fine-tune-event
    - fine_tuning.job.event
    - model
    type: string
    readOnly: true
    x-ms-enum:
      name: TypeDiscriminator
      modelAsString: true
      values:
      - value: list
        description: This object represents a list of other objects.
      - value: fine-tune
        description: This object represents a fine tune job.
      - value: fine_tuning.job
        description: This object represents a fine tune job.
      - value: file
        description: This object represents a file.
      - value: fine-tune-event
        description: This object represents an event of a fine tune job.
      - value: fine_tuning.job.event
        description: This object represents an event of a fine tuning job.
      - value: model
        description: This object represents a model (can be a base model or fine tune job result).
  FineTuningJob:
    title: FineTuningJob
    description: Defines the values of a fine tune job.
    required:
    - model
    - training_file
    type: object
    properties:
      object:
        $ref: '#/definitions/TypeDiscriminator'
      created_at:
        format: unixtime
        description: A timestamp when this job or item was created (in unix epochs).
        type: integer
        readOnly: true
      updated_at:
        format: unixtime
        description: A timestamp when this job or item was modified last (in unix epochs).
        type: integer
        readOnly: true
      id:
        description: The identity of this item.
        type: string
        readOnly: true
      status:
        $ref: '#/definitions/FineTuningState'
      model:
        description: The identifier (model-id) of the base model used for the fine-tune.
        minLength: 1
        type: string
      fine_tuned_model:
        description: "The identifier (model-id) of the resulting fine tuned model. This property is only populated for successfully completed fine-tune runs.\r\nUse this identifier to create a deployment for inferencing."
        type: string
      training_file:
        description: The file which is used for training.
        minLength: 1
        type: string
      validation_file:
        description: The file which is used to evaluate the fine tuned model during training.
        type: string
      result_files:
        description: "The result file identities (file-id) containing training and evaluation metrics in csv format.\r\nThe file is only available for successfully completed fine-tune runs."
        type: array
        items:
          type: string
      finished_at:
        format: int32
        description: A timestamp when this job or item has finished successfully (in unix epochs).
        type: integer
        readOnly: true
      organisation_id:
        description: The organisation id of this fine tune job. Unused on Azure OpenAI; compatibility for OpenAI only.
        type: string
      trained_tokens:
        format: int32
        description: The total number of billable tokens processed by this fine tuning job.
        type: integer
        readOnly: true
      hyperparameters:
        $ref: '#/definitions/FineTuningHyperParameters'
      suffix:
        description: The suffix used to identify the fine-tuned model. The suffix can contain up to 40 characters (a-z, A-Z, 0-9,- and _) that will be added to your fine-tuned model name.
        type: string
  FineTuningJobList:
    title: FineTuningJobList
    description: Represents a list of fine tunes.
    type: object
    properties:
      object:
        $ref: '#/definitions/TypeDiscriminator'
      data:
        description: The list of items.
        type: array
        items:
          $ref: '#/definitions/FineTuningJob'
      has_more:
        description: A value indicating whether the list of events contains more elements than returned.
        type: boolean
  FineTuningJobEvent:
    title: FineTuningJobEvent
    required:
    - created_at
    - level
    - message
    - type
    type: object
    properties:
      object:
        $ref: '#/definitions/TypeDiscriminator'
      id:
        description: The identity of this event.
        type: string
        readOnly: true
      created_at:
        format: unixtime
        description: A timestamp when this event was created (in unix epochs).
        type: integer
      level:
        $ref: '#/definitions/LogLevel'
      message:
        description: The message describing the event. This can be a change of state, e.g., enqueued, started, failed or completed, or other events like uploaded results.
        minLength: 1
        type: string
      type:
        $ref: '#/definitions/EventType'
      data:
        description: Machine readable data of this event.
  LogLevel:
    title: LogLevel
    description: The verbosity level of an event.
    enum:
    - info
    - warning
    - error
    type: string
    x-ms-enum:
      name: LogLevel
      modelAsString: true
      values:
      - value: info
        description: This event is for information only.
      - value: warning
        description: This event represents a mitigated issue.
      - value: error
        description: This message represents a non recoverable issue.
  FineTuningState:
    title: FineTuningState
    description: The state of a finetunes object or fine tuning job.
    enum:
    - created
    - pending
    - running
    - succeeded
    - cancelled
    - failed
    type: string
    readOnly: true
    x-ms-enum:
      name: FineTuningState
      modelAsString: true
      values:
      - value: created
        description: The operation was created. This state is not returned by Azure OpenAI and exposed only for compatibility. It can be categorized as an inactive state.
      - value: pending
        description: The operation is not yet queued to be processed in the future. It can be categorized as an inactive state.
      - value: running
        description: The operation has started to be processed. It can be categorized as an active state.
      - value: succeeded
        description: The operation has successfully be processed and is ready for consumption. It can be categorized as a terminal state.
      - value: cancelled
        description: The operation has been cancelled and is incomplete. It can be categorized as a terminal state.
      - value: failed
        description: The operation has completed processing with a failure and cannot be further consumed. It can be categorized as a terminal state.
  InnerError:
    title: InnerError
    description: "Inner error as defined in the Microsoft REST guidelines\r\n(https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses)."
    type: object
    properties:
      code:
        $ref: '#/definitions/InnerErrorCode'
      innererror:
        $ref: '#/definitions/InnerError'
  InnerErrorCode:
    title: InnerErrorCode
    description: "Inner error codes as defined in the Microsoft REST guidelines\r\n(https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses)."
    enum:
    - invalidPayload
    type: string
    x-ms-enum:
      name: InnerErrorCode
      modelAsString: true
      values:
      - value: invalidPayload
        description: The request data is invalid for this operation.
  FineTuningJobEventList:
    title: FineTuningJobEventList
    description: Represents a list of events.
    type: object
    properties:
      object:
        $ref: '#/definitions/TypeDiscriminator'
      data:
        description: The list of items.
        type: array
        items:
          $ref: '#/definitions/FineTuningJobEvent'
      has_more:
        description: A value indicating whether the list of events contains more elements than returned.
        type: boolean
  FineTuningJobCreation:
    title: FineTuningJobCreation
    description: Defines the values of a fine tune job.
    required:
    - model
    - training_file
    type: object
    properties:
      model:
        description: The identifier (model-id) of the base model used for this fine-tune.
        minLength: 1
        type: string
      training_file:
        description: The file identity (file-id) that is used for training this fine tuned model.
        minLength: 1
        type: string
      validation_file:
        description: The file identity (file-id) that is used to evaluate the fine tuned model during training.
        type: string
      hyperparameters:
        $ref: '#/definitions/FineTuningHyperParameters'
      suffix:
        description: The suffix used to identify the fine-tuned model. The suffix can contain up to 40 characters (a-z, A-Z, 0-9,- and _) that will be added to your fine-tuned model name.
        type: string
  EventType:
    title: EventType
    description: Defines the severity of a content filter result.
    enum:
    - message
    - metrics
    type: string
    x-ms-enum:
      name: EventType
      modelAsString: true
      values:
      - value: message
        description: Event only contains human readable messages.
      - value: metrics
        description: Event contains metrics.
  Error:
    title: Error
    description: "Error content as defined in the Microsoft REST guidelines\r\n(https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses)."
    required:
    - code
    - message
    type: object
    properties:
      code:
        $ref: '#/definitions/ErrorCode'
      message:
        description: The message of this error.
        minLength: 1
        type: string
      target:
        description: The location where the error happened if available.
        type: string
      details:
        description: The error details if available.
        type: array
        items:
          $ref: '#/definitions/Error'
      innererror:
        $ref: '#/definitions/InnerError'
    readOnly: true
  FineTuningHyperParameters:
    title: FineTuningHyperParameters
    description: The hyper parameter settings used in a fine tune job.
    type: object
    properties:
      n_epochs:
        format: int32
        description: The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset.
        type: integer
      batch_size:
        format: int32
        description: "The batch size to use for training. The batch size is the number of training examples used to train a single forward and backward pass.\r\nIn general, we've found that larger batch sizes tend to work better for larger datasets.\r\nThe default value as well as the maximum value for this property are specific to a base model."
        type: integer
      learning_rate_multiplier:
        format: double
        description: "The learning rate multiplier to use for training. The fine-tuning learning rate is the original learning rate used for pre-training multiplied by this value.\r\nLarger learning rates tend to perform better with larger batch sizes.\r\nWe recommend experimenting with values in the range 0.02 to 0.2 to see what produces the best results."
        type: number
parameters:
  apiVersionQueryParameter:
    in: query
    name: api-version
    description: The requested API version.
    required: true
    type: string
    x-ms-client-default: 2023-10-01-preview
    x-ms-parameter-location: client
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'