> ## Documentation Index > Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a model > Create a custom model and start a training job. The custom model cannot be modified after it is created. ## OpenAPI ````yaml /api-reference/saas/machine-learning-models.json post /customers/{CUSTOMER_ID}/ai/models openapi: 3.1.0 info: title: Lucidworks AI Models API version: '1.0' description: >- The Lucidworks AI Models API is used to discover available pre-trained and custom models, as well as train and deploy those models. The endpoints require an authentication token with scope `machinelearning.model`. contact: name: Lucidworks url: https://lucidworks.com/ email: support@lucidworks.com termsOfService: https://lucidworks.com/legal/developer-license-agreement/ license: name: Lucidworks url: https://lucidworks.com/legal/developer-license-agreement/ servers: - url: https://api.lucidworks.com security: [] tags: - name: Manage models description: View and create models. - name: Manage deployments description: View and create custom model deployments. paths: /customers/{CUSTOMER_ID}/ai/models: parameters: - schema: type: string name: CUSTOMER_ID in: path required: true description: Unique identifier derived from confidential client information. post: tags: - Manage models summary: Create a model description: >- Create a custom model and start a training job. The custom model cannot be modified after it is created. operationId: post-models requestBody: content: application/json: schema: $ref: '#/components/schemas/postModels' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/responsePostModels' components: schemas: postModels: title: postModels description: POST https://api.lucidworks.com/customers/{CUSTOMER_ID}/ai/models allOf: - properties: name: type: string description: The user-friendly name of the model. modelType: type: string description: The name of the custom model. region: type: string description: >- The geographic region specified when the custom model is being trained. trainingData: $ref: '#/components/schemas/trainingData' description: The location of the training data in Google Cloud Storage (GCS). config: $ref: '#/components/schemas/modelConfig' description: The configuration parameters passed to the model training job. trainingDataCredentials: type: object description: The credentials used to access the training data URLs. properties: serviceAccountKey: type: string description: The Base64-encoded service account JSON key. type: object responsePostModels: title: responsePostModels type: object properties: id: type: string description: >- The identifier of the model. The value is the universally unique identified (UUID) that is the primary key for the model. name: type: string description: The user-friendly name of the model. modelType: type: string description: The name of the model. category: type: string description: The object that specifies the model is `custom`. description: type: string description: The description of the model. region: type: string description: The geographic region specified when the custom model was trained. trainingData: $ref: '#/components/schemas/trainingData' description: The location of the training data in Google Cloud Storage (GCS). config: $ref: '#/components/schemas/modelConfig' description: The configuration parameters passed to the model training job. state: type: string description: >- This field specifies the current status of the custom model. The value is `TRAINING`. trainingStarted: type: string description: >- The date and time the training started. This field only applies to custom models. trainingCompleted: type: string description: >- The date and time the training completed. This field only applies to custom models. createdBy: type: string description: The user who created the model. trainingData: title: trainingData type: object description: >- Both the `catalog index file` and `signals query file` are required, and must contain the same `pkid` field, which links relevant queries to documents. properties: catalog: type: string description: >- The location of the catalog of the training data in Google Cloud Storage (GCS). The catalog file contains documents (products) that will be searched. The file must have a `pkid` (product key ID) column which contains the document ID or product ID. The `pkid` is a unique value for each document, so entries with a duplicate `pkid` are filtered out. However, since not every `pkid` entry is associated with a query, there may be entries in the `catalog index file` that are not associated with a `signals query entry`. The index file content format is different based on the model type to be trained. For example, a general model or an eCommerce model. - The general index file format contains: - `pkid` - The unique product key ID. Required field. This must match an entry in the `signals query file`. - `text` - A freeform text field. - The eCommerce index file format contains: - `pkid` - The unique product key ID. Required field. This must match an entry in the `signals query file`. - `name` - The freeform text field that contains the product name. signals: type: string description: >- The location of signals in the training data in Google Cloud Storage (GCS). The signals file must have a `pkid` (product key ID) column which refers to the relevant document or product ID. The file may contain multiple duplicates of any `pkid` because each document could be associated with several relevant queries. NOTE: For evaluation purposes, 10% of unique queries (50 minimum and 5000 maximum) are automatically sampled into a validation set from the training query file. * The general query file format contains: - `pkid` - The unique product key ID. Required field. This must match an entry in the `catalog index file`. - `query` - A freeform text field. - The eCommerce query file format contains: - `pkid` - The unique product key ID. Required field. This must match an entry in the `catalog index file`. - `query` - A freeform text field. - `aggr_count` - The number of documents that match the query criteria. In most cases, this value is used as a weight and must be greater than zero (0). If you do not use weights or there is no value, set this value to `1`. The weight is used for training pairs sampling and to compute normalized discounted cumulative gain (NDCG) metrics. If all values are `1.0`, binary NDCG is computed. required: - catalog - signals modelConfig: title: modelConfig type: object properties: dataset_config: type: string description: >- The options for the dataset format used for training are: - `mlp_general` - This is used for the general recurrent neural networks (RNN) model type. - `mlp_ecommerce` - This used for an eCommerce RNN model type. example: mlp_ecommerce trainer_config: type: string description: >- The options for the trainer type used for training are: - `mlp_general` - This is used for the general recurrent neural networks (RNN) model type. - `mlp_ecommerce` - This used for an eCommerce RNN model type. example: mlp_ecommerce trainer_config/text_processor_config: type: string description: >- This determines which type of tokenization and embedding is used as the base for the recurrent neural network (RNN) model. For example, word or bype-pair encoding (BPE). The word text processor defaults to English, and uses word-based tokenization and English pre-trained word embeddings. The maximum word vocabulary result is 100000. The BPE versions use the same tokenization, but different vocabulary sizes: * bpe_*_small embeddings have 10000 vocabulary tokens * bpe_*_large embeddings have 100000 vocabulary tokens * bpe_multi multilingual embeddings have 320000 vocabulary tokens The options for text processors are: - English - `word_en` (default) - `bpe_en_small` - `bpe_en_large` - `all_minilm_l6` - `e5_small_v2` - `e5_base_v2` - `e5_large_v2` - `gte_small` - `gte_base` - `gte_large` - `snowflake_arctic_embed_xs` - Multilingual - `bpe_multi` - `multilingual_e5_small` - `multilingual_e5_base` - `multilingual_e5_large` - Bulgarian - `bpe_bg_small` - `bpe_bg_large` - German - `bpe_de_small` - `bpe_de_large` - Spanish - `bpe_es_small` - `bpe_es_large` - French - `bpe_fr_small` - `bpe_fr_large` - Italian - `bpe_it_small` - `bpe_it_large` - Japanese - `bpe_ja_small` - `bpe_ja_large` - Korean - `bpe_ko_small` - `bpe_ko_large` - Dutch - `bpe_nl_small` - `bpe_nl_large` - Romanian - `bpe_ro_small` - `bpe_ro_large` - Chinese - `bpe_zh_small` - `bpe_zh_large` - Custom - `word_custom` - `bpe_custom` example: word_en trainer_config.encoder_config.rnn_names_list: type: array description: >- This determines which bi-directional recurrent neural network (RNN) layers are used. Options include `gru` and `lstm`. items: type: string example: gru trainer_config.encoder_config.rnn_units_list: type: array description: >- The number of units for each recurrent neural network (RNN) layer. IMPORTANT: You must specify the same number of units for `trainer_config.encoder_config.rnn_units_list` and its similarly-named `trainer_config.encoder_config.rnn_names_list` RNN layer. For example, `rnn_units_list` needs to be the same size as `rnn_names_list`. Because this is a bi-directional RNN, the encoder's vector size is two times larger than the number of units in the last layer. For example, if one layer is 128 units, the output vector size is 256. items: type: integer example: 128 trainer_config.trn_batch_size: type: integer description: >- The batch size to be used for a single model training update. By default, an appropriate batch size is automatically determined based on the dataset size. If the field is set to `null`, the batch size is also automatically determined based on the dataset size. trainer_config.num_epochs: type: integer description: >- The number of epochs the training data must complete. An epoch is a full cycle where training data passes through the designated algorithms. During one epoch, the model processes all the training data examples (queries and index documents) at least one time. example: 1 minimum: 1 maximum: 64 trainer_config.monitor_patience: type: integer description: >- The number of epochs the training passes before it stops if there is no validation metric improvement during the epochs. The best model state based on the monitor validation metric is used as the final model. * For the general RNN, the `mrr@3` metric is monitored and the `monitor_patience` default value is 8. * For the eCommerce RNN, the `ndcg@5` metric is monitored and the `monitor_patience` default value is 16. example: 8 trainer_config.encoder_config.emb_spdp: type: number description: >- This field provides a regularization effect, which is the process to simplify result answers. The regularization is applied between the token embeddings layer and the first recurrent neural network (RNN) layer. example: 0.3 format: float trainer_config.encoder_config.emb_trainable: type: boolean description: >- This field determines if fine-tuning of the token embeddings, such as word or byte pair encoding (BPE) token vectors, is enabled. If set, it can improve the quality of the model if the query contains less natural language, and training is negatively affected. Because the embeddings layer is the largest layer in the network, the process to improve the model requires enough training data to prevent overfitting. ````