Skip to content

Commit

Permalink
[ML] Improve docs around ML nodes and xpack.ml.enabled
Browse files Browse the repository at this point in the history
Since these docs were originally written there have been a couple
of changes:

1. We now support aarch64 as well as x86_64, so the SSE4.2 guidance
   needed clarification.
2. ML is more deeply embedded into Elasticsearch functionality
   across nodes that are not ML nodes. For example, ingest pipelines
   now routinely use ML, and, in the near future, index mappings
   will too in the form of semantic text. Although we cannot mandate
   that xpack.ml.enabled is set uniformly across the cluster, as
   that would be a breaking change, we should say ever more strongly
   that ML must be enabled on all nodes if all ML functionality is to
   work correctly. The primary reason for wanting to disable ML is
   hardware incompatibility, and if ML is disabled for that reason
   then it should not be used at all.
  • Loading branch information
droberts195 committed Feb 6, 2024
1 parent 4cf8942 commit 760e1b7
Showing 1 changed file with 18 additions and 4 deletions.
22 changes: 18 additions & 4 deletions docs/reference/settings/ml-settings.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,12 @@
// tag::ml-settings-description-tag[]
You do not need to configure any settings to use {ml}. It is enabled by default.

IMPORTANT: {ml-cap} uses SSE4.2 instructions, so it works only on machines whose
CPUs {wikipedia}/SSE4#Supporting_CPUs[support] SSE4.2. If you run {es} on older
hardware, you must disable {ml} (by setting `xpack.ml.enabled` to `false`).
IMPORTANT: {ml-cap} uses SSE4.2 instructions on x86_64 machines, so it works only
on x86_64 machines whose CPUs {wikipedia}/SSE4#Supporting_CPUs[support] SSE4.2.
(This limitation does not apply to aarch64 machines.) If you run {es} on older
x86_64 hardware, you must disable {ml} (by setting `xpack.ml.enabled` to `false`).
In this situation you should not attempt to use {ml} functionality in your cluster
at all.

// end::ml-settings-description-tag[]

Expand Down Expand Up @@ -46,7 +49,18 @@ that you use the default value for this setting on all nodes.
+
If set to `false`, the {ml} APIs are disabled on the node. For example, the node
cannot open jobs, start {dfeeds}, receive transport (internal) communication
requests, or requests from clients (including {kib}) related to {ml} APIs.
requests, or requests from clients (including {kib}) related to {ml} APIs. If
`xpack.ml.enabled` is not set uniformly across all nodes in your cluster then you
are likely to experience problems with {ml} functionality not fully working.
+
You must not use any {ml} functionality from ingest pipelines if `xpack.ml.enabled`
is `false` on any node. Before setting `xpack.ml.enabled` to `false` on a node,
consider whether you really meant to just exclude `ml` from the `node.roles`.
Excluding `ml` from the <<node-roles,`node.roles`>> will stop the node from
running {ml} jobs and NLP models, but it will still be aware that {ml} functionality
exists. Setting `xpack.ml.enabled` to `false` should be reserved for situations
where you cannot use {ml} functionality at all in your cluster due to hardware
limitations as described <<ml-settings-description,above>>.

`xpack.ml.inference_model.cache_size`::
(<<static-cluster-setting,Static>>) The maximum inference cache size allowed.
Expand Down

0 comments on commit 760e1b7

Please sign in to comment.