|
Mila
Deep Neural Network Library
|
Grouped-Query Attention module that accepts concatenated QKV input. More...
Public Types | |
| using | ComponentBase = Component<TDeviceType, TComputePrecision> |
| using | KvCacheTensorType = Tensor<kCacheDtype, MR> |
| using | MR = typename DeviceTypeTraits<TDeviceType>::memory_resource |
| using | OpType = typename Compute::OperationTraits<Compute::OperationType::GroupedQueryAttentionOp, TDeviceType, TComputePrecision, TKvPolicy>::type |
| using | TensorType = Tensor<TComputePrecision, MR> |
Public Member Functions | |
| GroupedQueryAttention (const std::string &name, const GqaConfig &config, std::optional< DeviceId > device_id=std::nullopt) | |
| Construct a GroupedQueryAttention component. | |
| TensorType & | backward (const TensorType &input, const TensorType &output_grad) |
| Run backward pass and return the component-owned input-gradient tensor. | |
| TensorType & | decode (const TensorType &q, const TensorType &k, const TensorType &v, dim_t position_offset) |
| Inference-only single-token decode pass. | |
| TensorType & | forward (const TensorType &input) |
| Standard forward pass. | |
| const GqaConfig & | getConfig () const noexcept |
| DeviceId | getDeviceId () const override |
| Get the compute device id associated with this component. | |
| std::vector< ITensor * > | getGradients () const override |
| Return non-owning pointers to parameter gradient tensors. | |
| MemoryStats | getMemoryStats () const override |
| Return the current memory allocation breakdown for this component. | |
| dim_t | getModelDim () const noexcept |
| dim_t | getNumHeads () const noexcept |
| dim_t | getNumKvHeads () const noexcept |
| std::vector< ITensor * > | getParameters () const override |
| Return non-owning pointers to parameter tensors. | |
| MemoryStats | getRequiredMemory (const BuildContext &context) const override |
| What onBuilding() would allocate for this context, without allocating. | |
| const ComponentType | getType () const override |
| Get the component type identifier. | |
| void | installSharedOutput (std::shared_ptr< TensorType > output) |
| Install a shared prefill-output slot (activation pooling). | |
| dim_t | parameterCount () const override |
| Return number of trainable parameters. | |
| TensorType & | prefill (const TensorType &q, const TensorType &k, const TensorType &v, dim_t position_offset) |
| Chunked prefill pass with explicit position offset. | |
| void | resetKVCache () |
| Reset the KV cache for a new generation session. | |
| bool | rewindKvCache (dim_t position) |
| Rewind the cache fill position for prompt-prefix reuse (PromptCaching.md). | |
| void | save_ (ModelArchive &, SerializationMode) const override |
| void | setState (const GqaState &state) |
| Forward the shared transient workspace to the underlying operation. | |
| void | setUseFlashDecode (bool enabled) |
| Route the BF16 decode through the fused decode-attention kernel. | |
| void | setUseFlashPrefill (bool enabled) |
| Route the BF16 prefill through the fused FlashAttention kernel. | |
| bool | supportsKVCache () const noexcept |
| Returns true when the underlying operation implements both IPositionalUnaryOp and IKVCacheLifecycle. | |
| void | synchronize () override |
| std::string | toString () const override |
| Produce a short, human-readable description of the component. | |
| Public Member Functions inherited from Mila::Dnn::Component< TDeviceType, TComputePrecision > | |
| Component (const std::string &name) | |
| Construct component with required name identifier. | |
| virtual void | build (const BuildContext &context) final |
| Build the component with the provided BuildContext (canonical overload). | |
| const std::string | getName () const |
| Get the component's name identifier. | |
| virtual std::vector< std::string > | getParameterNames () const |
| List all available parameter names for this component. | |
| TrainingMode | getTrainingMode () const noexcept |
| The current runtime behavioral mode of this Component. | |
| virtual bool | isBuilt () const final |
| Returns true if build() has completed successfully. | |
| virtual void | load_ (ModelArchive &archive, SerializationMode mode) |
| Restore this component's parameters from its archive scope. | |
| virtual void | loadParameter (const std::string &, const Serialization::ITensorBlob &) |
| Load a parameter from serialized tensor data. | |
| virtual void | requireSerializableParameters () const |
| Verify this component can serialize whatever parameters it owns. | |
| virtual void | saveFlatTensors (Serialization::SafeTensorsWriter &writer, const std::string &prefix, Serialization::TensorSavePass pass) const |
| Drive this component's tensors through one pass of a flat safetensors save. | |
| void | setTrainingMode (TrainingMode mode) |
| Set the runtime behavioral mode for this Component. | |
| virtual void | zeroGradients () |
| Clear all model-owned gradients for this component. | |
Static Public Attributes | |
| static constexpr TensorDataType | kCacheDtype |
| static constexpr bool | kKvCompressed = TKvPolicy::kIsActive |
Protected Member Functions | |
| void | onBuilding (const BuildContext &context) override |
| Hook invoked by build() to allocate component buffers. | |
| void | onExecutionContextSet () override |
| Lifecycle hook: Called immediately after ExecutionContext is set. | |
| void | onTrainingModeChanging (TrainingMode training_mode) override |
| Hook called before TrainingMode transitions. | |
| Protected Member Functions inherited from Mila::Dnn::Component< TDeviceType, TComputePrecision > | |
| IExecutionContext * | getExecutionContext () const |
| Get the shared execution context. | |
| bool | hasExecutionContext () const noexcept |
| Check if execution context has been set. | |
| void | loadParameterFromBlob (const std::string ¶m_name, const Serialization::ITensorBlob &blob, Tensor< TParameterPrecision, TMemoryResource > &target, const shape_t &expected_shape) |
| Load a tensor blob into a parameter tensor with validation. | |
| void | saveParameterToArchive (ModelArchive &archive, const std::string ¶meter_name, const Tensor< TParameterPrecision, TMemoryResource > ¶meter) const |
| Write one parameter tensor into the archive under "tensors/<name>". | |
| void | saveParameterToWriter (Serialization::SafeTensorsWriter &writer, const std::string &flat_name, const Tensor< TParameterPrecision, TMemoryResource > ¶meter, Serialization::TensorSavePass pass) const |
| Drive one parameter through one pass of a flat safetensors save. | |
| void | setExecutionContext (IExecutionContext *context) |
| Set the execution context for this component. | |
Additional Inherited Members | |
| Static Public Member Functions inherited from Mila::Dnn::Component< TDeviceType, TComputePrecision > | |
| static constexpr DeviceType | getDeviceType () |
| Compile-time device type for this component instance. | |
| static constexpr TensorDataType | getPrecision () noexcept |
| Compile-time tensor precision for this component instance. | |
| Protected Types inherited from Mila::Dnn::Component< TDeviceType, TComputePrecision > | |
| using | HostStagingMemoryResource |
| Host memory a device-resident parameter stages through. | |
| Protected Attributes inherited from Mila::Dnn::Component< TDeviceType, TComputePrecision > | |
| BuildContext | build_context_ |
| The BuildContext stored at build time. | |
Grouped-Query Attention module that accepts concatenated QKV input.
GQA generalises MHA by allowing num_kv_heads < num_heads. Each K/V head is shared by a group of (num_heads / num_kv_heads) Q heads, reducing KV cache memory and bandwidth during inference.
The module requires a single input tensor in model-layout containing concatenated Q, K and V along the feature axis:
input shape == [B, T, (num_heads + 2 * num_kv_heads) * head_dim] output shape == [B, T, model_dim] (model_dim = num_heads * head_dim)
The backend compute implementation (registered as "GroupedQueryAttentionOp") must accept this layout and produce the output above.
KV-cache inference is an optional backend capability. After build(), supportsKVCache() indicates whether the underlying operation implements both IPositionalUnaryOp (prefill/decode dispatch) and IKVCacheLifecycle (cache init/reset). Both pointers are resolved once at build time.
The cache self-initializes on the first prefill/forward; resetKVCache() is the public hook the owning decoder layer / transformer drives to start a new generation session.
REVIEW: resetKVCache() is public (initialization stays internal to prefill). When TransformerBase<> is introduced as the common base for GptTransformer, LlamaTransformer, MistralTransformer etc., revisit whether it should become private with 'friend class TransformerBase<TDeviceType, TPrecision>' to enforce that only the generate() orchestration path may manage the KV cache lifecycle.
|
inlineexplicit |
Construct a GroupedQueryAttention component.
| name | Component name identifier (mandatory). |
| config | GQA configuration (model_dim, num_heads, num_kv_heads). |
| device_id | Optional DeviceId to create an owned ExecutionContext (standalone / unit-test mode). |
|
inline |
Run backward pass and return the component-owned input-gradient tensor.
| input | Concatenated QKV input tensor used in forward. |
| output_grad | Gradient w.r.t. the module output. |
|
inline |
Inference-only single-token decode pass.
When the backend implements IPositionalUnaryOp and the cache has been populated by a prior forward() call, uses the fast O(n) KV cache path. When the backend does not support positional dispatch, falls back to forward(). The caller never needs to know which path was taken.
Precondition: forward() must have been called at least once to populate the KV cache before decode() is called.
| q | Query tensor [B, 1, Q * head_dim]. |
| k | Key tensor [B, 1, KV * head_dim]. |
| v | Value tensor [B, 1, KV * head_dim]. |
| position_offset | Absolute position of the token (0-based). |
|
inline |
Standard forward pass.
Always available regardless of backend. When the backend supports KV caching, the first forward() call initialises and populates the cache (prefill with position_offset=0). When called again after decode() steps, it automatically resets the cache and begins a new prefill session – no explicit session management required by callers.
| input | Concatenated QKV input [B, T, (Q + 2*KV) * head_dim]. |
|
inlineoverridevirtual |
Get the compute device id associated with this component.
Must return the device on which parameters and operations execute.
Implements Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inlineoverridevirtual |
Return non-owning pointers to parameter gradient tensors.
Gradient buffers are allocated only when the component is built in training mode, so a component built for inference returns an empty vector. Stateless components return empty in either mode. This is the accessor counterpart to getParameters() and does not throw on mode.
| std::runtime_error | if called before the component has been built. |
Implements Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inlineoverridevirtual |
Return the current memory allocation breakdown for this component.
Reflects allocations at the moment of the call. The returned stats naturally track the component lifecycle:
After construction – nothing; construction allocates none After build( Inference ) – parameters + T=1 state buffers After build( Training ) – parameters + T=full state buffers After setTrainingMode( Train ) – parameters + state + gradients
For CompositeComponent and Network, the returned stats are the recursive aggregate of all child components.
May be called at any time – no lifecycle preconditions.
Implements Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inlineoverridevirtual |
Return non-owning pointers to parameter tensors.
The returned tensor pointers remain valid for the lifetime of the component. Order should be canonical (weights before biases).
Implements Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inlineoverridevirtual |
What onBuilding() would allocate for this context, without allocating.
The KV cache – the dominant, context-scaling term – is reported by the operation, which is where it is allocated. See Specifications/MemoryFootprint.md.
Reimplemented from Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inlineoverridevirtual |
Get the component type identifier.
Used for serialization and runtime type identification.
Implements Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inline |
Install a shared prefill-output slot (activation pooling).
Must be called before build(): onBuilding then skips the prefill output self-allocation after validating the slot's storage covers the build shape; prefill() already always returns a shape-adjusted view. The tiny per-token decode output (decode_output_) stays component-owned. Mirrors Linear::installSharedWeight; self-allocation remains the default. The slot is owned and memory-accounted by the installer.
|
inlineoverrideprotectedvirtual |
Hook invoked by build() to allocate component buffers.
Receives the stored BuildContext. Implementations must use config.allocationSeqLen() when sizing output buffers – this is the single call that makes Inference and Training allocate the correct buffer sizes automatically without per-component logic.
The default implementation forwards to the legacy onBuilding( const shape_t& ) overload for backwards compatibility. New components should override this overload directly.
Takes the build-time configuration; use its allocationSeqLen() to obtain the correct output buffer sequence dimension.
Reimplemented from Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inlineoverrideprotectedvirtual |
Lifecycle hook: Called immediately after ExecutionContext is set.
Override this to perform initialization that requires a valid ExecutionContext. At the time this is called, getExecutionContext() is guaranteed to return a valid context.
Common uses:
Default implementation does nothing.
| Any | exception thrown will cause setExecutionContext() to fail and restore the component to a "context not set" state. |
Reimplemented from Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inlineoverrideprotectedvirtual |
Hook called before TrainingMode transitions.
Called by setTrainingMode() after validation and lock acquisition, before the internal state is updated. Derived classes override to respond to the transition – e.g. zeroing gradient buffers on transition to Eval, or re-enabling dropout on transition to Training.
The default implementation is a no-op.
Takes the incoming TrainingMode.
Reimplemented from Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inlineoverridevirtual |
Return number of trainable parameters.
For leaf components this is the element count of owned parameter tensors. CompositeComponent and Network implementations should return the recursive aggregate across all children.
Implements Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inline |
Chunked prefill pass with explicit position offset.
Called by the transformer block during chunked prefill. The KV cache must already be initialized (via onBuilding or forward()).
| q | Query tensor [B, T_chunk, Q * head_dim]. |
| k | Key tensor [B, T_chunk, KV * head_dim]. |
| v | Value tensor [B, T_chunk, KV * head_dim]. |
| position_offset | Absolute position of the first token in this chunk. |
|
inline |
Reset the KV cache for a new generation session.
Drops any active decode state so the next prefill starts a fresh sequence. A no-op on backends without KV-cache support, and harmless when no decode session is active.
|
inline |
Rewind the cache fill position for prompt-prefix reuse (PromptCaching.md).
Unlike resetKVCache() the cache session stays live: initialization state and device contents are untouched, and positions [0, position) remain valid for a subsequent prefillFrom.
|
inlineoverridevirtual |
|
inline |
|
inline |
Route the BF16 decode through the fused decode-attention kernel.
Only the CUDA BF16 ops honor this; other backends, FP32, and unsupported geometries keep the cuBLASLt decode pipeline. Unlike setUseFlashPrefill there is no workspace-width coupling – the fused path draws its split-K scratch from the shared execution-context buffer at decode time.
|
inline |
Route the BF16 prefill through the fused FlashAttention kernel.
Only the CUDA BF16 ops honor this – the unbounded/global kernel and the bounded sliding-window ring variant; other backends and FP32 ignore it. The transformer couples this to the shared preatt/att workspace width (flash on -> the O(chunk x T_ctx) score buffer is reclaimed), so it must be set consistently with that sizing – a narrow workspace with flash off would overflow. See GqaFlashAttention.md 5.6.
|
inlinenoexcept |
Returns true when the underlying operation implements both IPositionalUnaryOp and IKVCacheLifecycle.
Resolved once at build time. CPU backends return false; CUDA backends return true when CudaGroupedQueryAttentionOp is in use.
|
inlineoverridevirtual |
@brief Convenience accessor -- true if currently in Eval mode.
Equivalent to getTrainingMode() == TrainingMode::Eval.
Valid for both RuntimeMode::Inference and RuntimeMode::Training
built components.
@return true if in Eval mode.
‍/
bool isEvalMode() const noexcept { return getTrainingMode() == TrainingMode::Eval; }
RuntimeMode getRuntimeMode() const noexcept
{
return build_context_.getRuntimeMode();
}
bool isInferenceMode() const noexcept
{
return build_context_.isInferenceMode();
}
bool isTrainingMode() const noexcept
{
return build_context_.isTrainingMode();
}
====================================================================
/**
@brief Wait for outstanding device work submitted by this component.
On CPU this may be a no-op. Use to ensure results are visible to
the host or to measure synchronous timings.
Implements Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
inlineoverridevirtual |
Produce a short, human-readable description of the component.
Implementations should keep output concise and avoid throwing.
Implements Mila::Dnn::Component< TDeviceType, TComputePrecision >.
|
staticconstexpr |