#ivddlmZddlZddlZddlZddlZddlmZddlm Z ddl m Z m Z m Z ddlZddlm ZddlZddlmZmZddlmZddlmZmZdd lmZdd lmZdd lmZdd l m!Z!dd l"m#Z#ddl$m%Z%ddl&m'Z'ddl(m)Z)ddl*m+Z+m,Z,ddl-m.Z.m/Z/ddl0m1Z1ddl2m3Z3ejhe5Z6Gdde!Z7y)) annotationsN)Callable)Queue)AnyLiteraloverload)Tensornn)trange) AutoConfigPretrainedConfig)PreTrainedModel)logging) deprecated) BaseModel) TextInput) Transformer)Pooling)SparseEncoderModelCardData)SparseAutoEncoder SpladePooling)batch_to_deviceselect_max_active_dims)deprecated_kwargs)SimilarityFunctionceZdZUdZeZdZded<dddZded<d Z e d  d2dddddd dd dddddd ddd d3fdZ e d d4 d5dZ e d d4 d5dZ e d d4 d5dZd6fd Zd7fd Zed8dZej& d9dZd:dZed;dZed d?d Ze d@d!ZdAd"Zed#e$dAd%Z dB dCd&Z dD dEd'Z edFd(Z!edGfd) Z"e"j&dHd*Z"edIfd+ Z#dJd,Z$edAd-Z%e%j&dKd.Z%e dLd/Z& d2 dMd0Z'dNd1Z(xZ)S)O SparseEncodera Loads or creates a SparseEncoder model that can be used to map text to sparse embeddings. Args: model_name_or_path (str, optional): If a filepath on disk, loads the model from that path. Otherwise, tries to download a pre-trained SparseEncoder model. If that fails, tries to construct a model from the Hugging Face Hub with that name. Defaults to None. modules (list[nn.Module], optional): A list of torch modules that are called sequentially. Can be used to create custom SparseEncoder models from scratch. Defaults to None. device (str, optional): Device (like ``"cuda"``, ``"cpu"``, ``"mps"``, ``"npu"``) that should be used for computation. If None, checks if a GPU can be used. Defaults to None. prompts (dict[str, str], optional): A dictionary with prompts for the model. The key is the prompt name, the value is the prompt text. The prompt text will be prepended before any text to encode. For example: ``{"query": "query: ", "passage": "passage: "}``. If a model has saved prompts, you can override them by passing your own, or pass ``{"query": "", "document": ""}`` to disable them. Defaults to None. default_prompt_name (str, optional): The name of the prompt that should be used by default. If not set, no prompt will be applied. Defaults to None. cache_folder (str, optional): Path to store models. Can also be set by the ``SENTENCE_TRANSFORMERS_HOME`` environment variable. Defaults to None. trust_remote_code (bool, optional): Whether to allow for custom models defined on the Hub in their own modeling files. Only set to ``True`` for repositories you trust and in which you have read the code, as it will execute code present on the Hub on your local machine. Defaults to False. revision (str, optional): The specific model version to use. It can be a branch name, a tag name, or a commit id, for a stored model on Hugging Face. Defaults to None. local_files_only (bool, optional): Whether to only look at local files (i.e., do not try to download the model). Defaults to False. token (bool or str, optional): Hugging Face authentication token to download private models. Defaults to None. model_kwargs (dict[str, Any], optional): Keyword arguments passed to the underlying Hugging Face Transformers model via ``AutoModel.from_pretrained``. Particularly useful options include: - ``torch_dtype``: Override the default ``torch.dtype`` and load the model under a specific dtype. Can be ``torch.float16``, ``torch.bfloat16``, ``torch.float32``, or ``"auto"`` to use the dtype from the model's ``config.json``. - ``attn_implementation``: The attention implementation to use. For example ``"eager"``, ``"sdpa"``, or ``"flash_attention_2"``. If you ``pip install kernels``, then ``"flash_attention_2"`` should work without having to install ``flash_attn``. It is frequently the fastest option. Defaults to ``"sdpa"`` when available (torch>=2.1.1). - ``device_map``: Device map for model parallelism, e.g. ``"auto"``. - ``provider``: For ``backend="onnx"``, the ONNX execution provider (e.g. ``"CUDAExecutionProvider"``). - ``file_name``: For ``backend="onnx"`` or ``"openvino"``, the filename to load (e.g. for optimized or quantized models). - ``export``: For ``backend="onnx"`` or ``"openvino"``, whether to export the model to the backend format. Also set automatically if the exported file doesn't exist. See the `PreTrainedModel.from_pretrained `_ documentation for more details. Defaults to None. processor_kwargs (dict[str, Any], optional): Keyword arguments passed to the Hugging Face Transformers processor/tokenizer via ``AutoProcessor.from_pretrained``. See the `AutoTokenizer.from_pretrained `_ documentation for more details. Defaults to None. config_kwargs (dict[str, Any], optional): Keyword arguments passed to the Hugging Face Transformers config via ``AutoConfig.from_pretrained``. See the `AutoConfig.from_pretrained `_ documentation for more details. Defaults to None. model_card_data (:class:`~sentence_transformers.sparse_encoder.model_card.SparseEncoderModelCardData`, optional): A model card data object that contains information about the model. Used to generate a model card when saving the model. If not set, a default model card data object is created. Defaults to None. backend (str, optional): The backend to use for inference. Can be ``"torch"`` (default), ``"onnx"``, or ``"openvino"``. Defaults to ``"torch"``. similarity_fn_name (str or SimilarityFunction, optional): The name of the similarity function to use. Valid options are ``"cosine"``, ``"dot"``, ``"euclidean"``, and ``"manhattan"``. If not set, it is automatically set to ``"cosine"`` when :attr:`similarity` or :attr:`similarity_pairwise` are first accessed. Defaults to None. max_active_dims (int, optional): The maximum number of active (non-zero) dimensions in the output of the model. ``None`` means no limit, which can be slow or memory-intensive if your model wasn't (yet) finetuned to high sparsity. Defaults to None. Example: :: from sentence_transformers import SparseEncoder # Load a pre-trained SparseEncoder model model = SparseEncoder('naver/splade-cocondenser-ensembledistil') # Encode some texts sentences = [ "The weather is lovely today.", "It's so sunny outside!", "He drove to the stadium.", ] embeddings = model.encode(sentences) print(embeddings.shape) # (3, 30522) # Get the similarity scores between all sentences similarities = model.similarity(embeddings, embeddings) print(similarities) # tensor([[ 35.629, 9.154, 0.098], # [ 9.154, 27.478, 0.019], # [ 0.098, 0.019, 29.553]]) zsparse-encoder str | None default_huggingface_organizationN)querydocumentzdict[str, str | None]_default_promptssparse_encoder_model_idprocessor_kwargs)tokenizer_kwargsFtorch)modulesdevicepromptsdefault_prompt_name cache_foldertrust_remote_coderevisionlocal_files_onlytoken model_kwargsr$ config_kwargsmodel_card_databackendsimilarity_fn_namemax_active_dimsc||_t| ||||||| | | | | |||||||dkrtd|d||_|C|j j D]%}t|ts|j|_yyy)N)model_name_or_pathr'r(r+r,r-r.r/r0r$r1r2r3r)r*rz0max_active_dims must be a positive integer, got .) r4super__init__ ValueErrorr5_modulesvalues isinstancerk)selfr7r'r(r)r*r+r,r-r.r/r0r$r1r2r3r4r5module __class__s {/var/www/vps2.regionflexible.com/Desarrollo/venv/lib/python3.12/site-packages/sentence_transformers/sparse_encoder/model.pyr:zSparseEncoder.__init__s0#5 1%/-%-'+ 3  $  &?a+?OP_O``abc c.  "--..0 f&78+188D(  #inputs) sentencesc  j||d|jvrd}|jd||||||||| | | | dd | S)aG Computes embeddings specifically optimized for query representation. This method is a specialized version of :meth:`encode` that differs in exactly two ways: 1. If no ``prompt_name`` or ``prompt`` is provided, it uses a predefined "query" prompt, if available in the model's ``prompts`` dictionary. 2. It sets the ``task`` to "query". If the model has a :class:`~sentence_transformers.base.modules.Router` module, it will use the "query" task type to route the input through the appropriate submodules. .. tip:: Adjusting ``batch_size`` can significantly improve processing speed. The optimal value depends on your hardware, model size, precision, and input length. Benchmark a few batch sizes on a small subset of your data to find the best value. All other parameters are identical to :meth:`encode`. See :meth:`encode` for the full parameter documentation. Example: :: from sentence_transformers import SparseEncoder # Load a pre-trained SparseEncoder model model = SparseEncoder("naver/splade-cocondenser-ensembledistil") # Encode some texts queries = [ "What are the effects of climate change?", "History of artificial intelligence", "Technical specifications product XYZ", ] embeddings = model.encode_query(queries) print(embeddings.shape) # (3, 30522) r rE prompt_nameprompt batch_sizeshow_progress_barconvert_to_tensorconvert_to_sparse_tensor save_to_cpur(r5pool chunk_sizetaskr)encode)r@rErIrJrKrLrMrNrOr(r5rPrQkwargss rC encode_queryzSparseEncoder.encode_queryshj  6>g6M!Kt{{ #!//%=#+!   rDc  |||dD]}||jvs|}n|jd||||||||| | | | dd | S)a Computes embeddings specifically optimized for document/passage representation. This method is a specialized version of :meth:`encode` that differs in exactly two ways: 1. If no ``prompt_name`` or ``prompt`` is provided, it uses the first available prompt from the following candidates: ``"document"``, ``"passage"``, ``"corpus"`` (checked in that order). 2. It sets the ``task`` to "document". If the model has a :class:`~sentence_transformers.base.modules.Router` module, it will use the "document" task type to route the input through the appropriate submodules. .. tip:: Adjusting ``batch_size`` can significantly improve processing speed. The optimal value depends on your hardware, model size, precision, and input length. Benchmark a few batch sizes on a small subset of your data to find the best value. All other parameters are identical to :meth:`encode`. See :meth:`encode` for the full parameter documentation. Example: :: from sentence_transformers import SparseEncoder # Load a pre-trained SparseEncoder model model = SparseEncoder("naver/splade-cocondenser-ensembledistil") # Encode some texts sentences = [ "This research paper discusses the effects of climate change on marine life.", "The article explores the history of artificial intelligence development.", "This document contains technical specifications for the new product line.", ] embeddings = model.encode_document(sentences) print(embeddings.shape) # (3, 30522) )r!passagecorpusr!rHrSrT)r@rErIrJrKrLrMrNrOr(r5rPrQrVcandidate_prompt_names rCencode_documentzSparseEncoder.encode_document s~j  6>)J %(DLL8"7K  t{{ #!//%=#+!   rDc  |4tjtjtjfv}|dkrt d|d|j |}|r|g}nEt|ts5t|tjr|jn t|}|j}t| t|z dhz x}rnt |jjdt|d|r#d|jjd |dzd|jjd z| t| tr6t!| dkDr(|j"d||| | | |||||d | d | }|r|d}|S|j%||}| |j&} |j)| |j+| | n |j,} t/| }| | |d <g}tj0|Dcgc]}|j3| c}}|j5r|j7|}|Dcgc]}|| }}t9dt!||d| D]}||||z}|j:|fd|i| }t=|| }t?j@5|jB|fi|d}| tE|| }ddd|rjG}|rjI}|jKtj0|Dcgc]}|| }}|rit!|dk(rFt?jLg|j&}|r|jG}|r&|jI}nt?jN|}|r|d}|Scc}wcc}w#1swYxYwcc}w)a Computes sparse sentence embeddings. .. tip:: If you are unsure whether you should use :meth:`encode`, :meth:`encode_query`, or :meth:`encode_document`, your best bet is to use :meth:`encode_query` and :meth:`encode_document` for Information Retrieval tasks with clear query and document/passage distinction, and use :meth:`encode` for all other tasks. Note that :meth:`encode` is the most general method and can be used for any task, including Information Retrieval, and that if the model was not trained with predefined prompts and/or task types, then all three methods will return identical embeddings. .. tip:: Adjusting ``batch_size`` can significantly improve processing speed. The optimal value depends on your hardware, model size, precision, and input length. Benchmark a few batch sizes on a small subset of your data to find the best value. Args: inputs (Union[str, List[str]]): The texts to embed. prompt_name (str, optional): The name of the prompt to use for encoding. Must be a key in the ``prompts`` dictionary, which is either set in the constructor or loaded from the model configuration. For example if ``prompt_name`` is "query" and the ``prompts`` is {"query": "query: ", ...}, then the sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?" because the sentence is appended to the prompt. If ``prompt`` is also set, this argument is ignored. Defaults to None. prompt (str, optional): The prompt to use for encoding. For example, if the prompt is "query: ", then the sentence "What is the capital of France?" will be encoded as "query: What is the capital of France?" because the sentence is appended to the prompt. If ``prompt`` is set, ``prompt_name`` is ignored. Defaults to None. batch_size (int, optional): The batch size used for the computation. Defaults to 32. show_progress_bar (bool, optional): Whether to output a progress bar when encoding. Defaults to None, in which case the progress bar will be shown if the logger's effective level is INFO or DEBUG. convert_to_tensor (bool, optional): Whether the output should be a single stacked tensor (True) or a list of individual tensors (False). Sparse tensors may be challenging to slice, so this allows you to output lists of tensors instead. Defaults to True. convert_to_sparse_tensor (bool, optional): Whether the output should be in the format of a sparse (COO) tensor. Defaults to True. save_to_cpu (bool, optional): Whether the output should be moved to cpu or stay on the device it has been computed on. Defaults to False. device (str, torch.device, list, or None, optional): Device(s) to use for computation. Can be: - A single device string (e.g., "cuda:0", "cpu") for single-process encoding - A list of device strings (e.g., ["cuda:0", "cuda:1"], ["cpu", "cpu", "cpu", "cpu"]) to distribute encoding across multiple processes - None to auto-detect available device for single-process encoding If a list is provided, multi-process encoding will be used. Defaults to None. max_active_dims (int, optional): The maximum number of active (non-zero) dimensions in the output of the model. ``None`` means the value from the model's config will be used. Defaults to None. If also None in the model's config, there will be no limit on the number of active dimensions, which can be slow or memory-intensive if your model wasn't (yet) finetuned to high sparsity. pool (dict, optional): A pool created by :meth:`start_multi_process_pool` for multi-process encoding. If provided, the encoding will be distributed across multiple processes. This is recommended for large datasets and when multiple GPUs are available. Defaults to None. chunk_size (int, optional): Size of chunks for multi-process encoding. Only used with multiprocessing, i.e. when ``pool`` is not None or ``device`` is a list. If None, a sensible default is calculated. Defaults to None. Returns: Union[list[Tensor], Tensor]: By default, a 2d torch sparse tensor with shape [num_inputs, output_dimension] is returned. If only one string input is provided, then the output is a 1d tensor with shape [output_dimension]. If ``convert_to_tensor`` is False, a list of individual tensors is returned instead. Example: :: from sentence_transformers import SparseEncoder # Load a pre-trained SparseEncoder model model = SparseEncoder("naver/splade-cocondenser-ensembledistil") # Encode some texts sentences = [ "The weather is lovely today.", "It's so sunny outside!", "He drove to the stadium.", ] embeddings = model.encode(sentences) print(embeddings.shape) # (3, 30522) Nrz+batch_size must be a positive integer, got r8rRzZ.encode() has been called with additional keyword arguments that this model does not use: z. zAs per zA.get_model_kwargs(), the valid additional keyword arguments are: zQ.get_model_kwargs(), this model does not accept any additional keyword arguments.T) rErLrPr(rQrIrJrKrMrNrOr5r5BatchesdescdisablerJsentence_embedding)r5)r(rS)(loggergetEffectiveLevelrINFODEBUGr;is_singular_inputr>listnpndarraytolistget_model_kwargssetrB__name__len_multi_process_resolve_promptr(toevalr5dictargsort _input_length_can_flatten_inputs_interleave_sorted_indicesr preprocessrr&inference_modeforwardr to_sparsecpuextendtensorstack)r@rErIrJrKrLrMrNrOr(r5rPrQrVrgr0 unused_kwargs embeddingsforward_kwargsall_embeddingssenlength_sorted_idxidx inputs_sorted start_index inputs_batchfeaturess rCrUzSparseEncoder.encodeVs/F  $ & 8 8 :  ?!  ?J:,VWXY Y!226: XFFD)(262::(FV]]_DQWLF,,. K#l*;;vhF F= F>>**+,FGKLYGZF[[]^$dnn5566wyExFFGH  #4>>#:#:";[[F  -<-H/dNbNbf  &0?N, -JJF'SS););C)@(@'ST  # # % $ ? ?@Q R 0ABB B!!S[*9ZkVkl .K({Z7OPL&t|MFMfMH&x8H%%' e)T\\(EnEFZ[ ".!7 Tc!dJ  e ('113 '^^-  ! !* -! .$:<DU9VW#.-WW >"a'!&b!E+%3%=%=%?N%3%7%7%9N!&^!< +A.NM(TC e eXsN- N2/&N7+ O7O c>t|d|jizSNr4)r9_get_model_config_similarity_fn_namer@rBs rCrzSparseEncoder._get_model_config&s(w(* $":":.   rDclt|||j|jdd|_yyr)r9_parse_model_configrgetr4)r@ model_configrBs rCrz!SparseEncoder._parse_model_config+s7 #L1  # # +&2&6&67KT&RD # ,rDc\|jtj|_|jS)aReturn the name of the similarity function used by :meth:`SparseEncoder.similarity` and :meth:`SparseEncoder.similarity_pairwise`. Returns: Literal["cosine", "dot", "euclidean", "manhattan"]: The name of the similarity function. Defaults to "dot" when first accessed if not explicitly set. Example: >>> model = SparseEncoder("naver/splade-cocondenser-ensembledistil") >>> model.similarity_fn_name 'dot' )rrDOTr4r@s rCr4z SparseEncoder.similarity_fn_name0s*  # # +&8&<&rvaluerto_similarity_fn _similarityto_similarity_pairwise_fn_similarity_pairwiser@rs rCr4z SparseEncoder.similarity_fn_nameAsR e/ 0KKE#(  1BB5ID (:(T(TUZ([D % rDcD|D]}t|ts||_yy)a8 Sets the ``include_prompt`` attribute in the pooling layer in the model, if there is one. This is useful for models where the prompt should be excluded from the pooling strategy, e.g. CSR models with a :class:`~sentence_transformers.sentence_transformer.modules.Pooling` layer. N)r>rinclude_prompt)r@rrAs rCset_pooling_include_promptz(SparseEncoder.set_pooling_include_promptNs( F&'*(6% rDcyrrSr@ embeddings1 embeddings2s rC similarityzSparseEncoder.similarityZsNQrDcyrrSrs rCrzSparseEncoder.similarity]spsrDc2|j|jS)aQ Compute the similarity between two collections of embeddings. The output will be a matrix with the similarity scores between all embeddings from the first parameter and all embeddings from the second parameter. This differs from `similarity_pairwise` which computes the similarity between each pair of embeddings. This method supports only embeddings with fp32 precision and does not accommodate quantized embeddings. Args: embeddings1 (Union[Tensor, ndarray]): [num_embeddings_1, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor. embeddings2 (Union[Tensor, ndarray]): [num_embeddings_2, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor. Returns: Tensor: A [num_embeddings_1, num_embeddings_2]-shaped torch tensor with similarity scores. Example: :: >>> model = SparseEncoder("naver/splade-cocondenser-ensembledistil") >>> sentences = [ ... "The weather is so nice!", ... "It's so sunny outside.", ... "He's driving to the movie theater.", ... "She's going to the cinema.", ... ] >>> embeddings = model.encode(sentences) >>> model.similarity(embeddings, embeddings) tensor([[ 30.953, 12.871, 0.000, 0.011], [ 12.871, 27.505, 0.580, 0.578], [ 0.000, 0.580, 36.068, 15.301], [ 0.011, 0.578, 15.301, 39.466]]) >>> model.similarity_fn_name "dot" >>> model.similarity_fn_name = "cosine" >>> model.similarity(embeddings, embeddings) tensor([[ 1.000, 0.441, 0.000, 0.000], [ 0.441, 1.000, 0.018, 0.018], [ 0.000, 0.018, 1.000, 0.406], [ 0.000, 0.018, 0.406, 1.000]]) )r4rrs rCrzSparseEncoder.similarity`sR rDcyrrSrs rCsimilarity_pairwisez!SparseEncoder.similarity_pairwisesWZrDcyrrSrs rCrz!SparseEncoder.similarity_pairwisesrDc2|j|jS)a Compute the similarity between two collections of embeddings. The output will be a vector with the similarity scores between each pair of embeddings. This method supports only embeddings with fp32 precision and does not accommodate quantized embeddings. Args: embeddings1 (Union[Tensor, ndarray]): [num_embeddings, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor. embeddings2 (Union[Tensor, ndarray]): [num_embeddings, embedding_dim] or [embedding_dim]-shaped numpy array or torch tensor. Returns: Tensor: A [num_embeddings]-shaped torch tensor with pairwise similarity scores. Example: :: >>> model = SparseEncoder("naver/splade-cocondenser-ensembledistil") >>> sentences = [ ... "The weather is so nice!", ... "It's so sunny outside.", ... "He's driving to the movie theater.", ... "She's going to the cinema.", ... ] >>> embeddings = model.encode(sentences, convert_to_sparse_tensor=False) >>> model.similarity_pairwise(embeddings[::2], embeddings[1::2]) tensor([12.871, 15.301]) >>> model.similarity_fn_name "dot" >>> model.similarity_fn_name = "cosine" >>> model.similarity_pairwise(embeddings[::2], embeddings[1::2]) tensor([0.441, 0.406]) )r4rrs rCrz!SparseEncoder.similarity_pairwisesH (((rDc |jdd}d|d<d}|#t|tr|j|}d} |Ft t j t|t|dz dz d}t|d}|d } |d } |r!t j t||z nd } t| D]#} | |z} || | |z}| j| ||g%tt| d | Dcgc]}| jc}d}|D]}t|dts|d|Dcgc]}|d }}|rt|d tr)ttjj!|}n~t|d t"j$rt#j&|}nKt|d t(j*r.t)j,|d }n|rt#j$}||r|j/|SScc}wcc}w#|r|j/|wwxYw)aInternal method for multi-process encoding. Distributes encoding across multiple processes using the provided pool or list of devices. If a pool is not provided but ``device`` is a list, a pool is created and cleaned up automatically. rMFrLT processes iinputoutputrChunksr_c |dS)NrrS)xs rCz.SparseEncoder._multi_process..s adrD)key)axis)rr>rhstart_multi_process_poolminmathceilromaxrangeputsortedr Exception itertoolschain from_iterabler&r catrirj concatenatestop_multi_process_pool)r@rErLrPr(rQ encode_kwargsrM created_pool input_queue output_queue num_chunkschunk_id chunk_startchunk_ output_listrrs rCrpzSparseEncoder._multi_processs2*--.A5I-2 )* >&)>J>jmT2!%ioo&C&CJ&O!PJ 1 u||H,>H""H,8 H, H'B?H," H,,Ic |j\}}}|j|fd|i|}t|tjr)|j j dk7r|j}|j||g#tj$rYyt$rI}tjd|d| |j|gn#t$rYnwxYwYd}~yd}~wwxYw)zInternal working process to encode sentences in multi-process setup. Workers are terminated externally via ``stop_multi_process_pool``. r(r}zError in worker process on z: N)rrUr>r&r r(typer}rqueueEmptyrrcerror) target_devicemodelr results_queuerrErVres rC_multi_process_workerz#SparseEncoder._multi_process_workers +6??+<(&&)U\\&QQ&Q j%,,7JK|]}|jdyw) ForMaskedLMN)endswith).0archs rC z6SparseEncoder._load_default_modules..csqD4==7qs architecturesNz fill-mask)transformer_taskrr0r$r1r3z.Detected MLM architecture, using SpladePoolingr)pooling_strategyz`No MLM architecture detected, using default Transformer + mean Pooling + SparseAutoEncoder (CSR)zfeature-extractionmean) pooling_modei input_dim hidden_dimr?k_aux)r-)r from_pretrainedanyrrr3rcinforrrrr2set_base_model)r@r7r/r+r-r,r.r0r$r1 shared_kwargsconfig is_mlm_modeltransformer_model pooling_modelr'poolingsaes rC_load_default_modulesz#SparseEncoder._load_default_modules5sB!2 0  A-@L,>B@ HmH0@0FBHB=B]-@bB #-#=#= $ *6$ :G$ qGFTceiDjDpnpqq  +"!,&)!1+ !  KKH I)5AM(-8G KKr !,"!5&)!1+ ! /GGIX^_G#!99;w>>@@ C )'37G  / /0BX / V{rDc  | dk7r|j|||||||||  S||||d} i| |xsi}i| |xsi}i| | xsi} tjd|j|||||||||  \} |_t | j } d} t| D] }t|ds|j} n| tdt| d| z| dz| d z }| j|d|_ | |jfS) a)Converts a non-SparseEncoder model into a SparseEncoder by appending a SparseAutoEncoder. If ``model_type`` is ``"SentenceTransformer"``, loads the SentenceTransformer modules and appends a SparseAutoEncoder on top. Otherwise, falls back to :meth:`_load_default_modules`. SentenceTransformer)r/r+r-r,r.r0r$r1rzWSentenceTransformer model found, appending SparseAutoEncoder on top to form a CSR modelNrzCannot determine the embedding dimension from the loaded modules. At least one module must have a `get_embedding_dimension` method.rr)rrcr_load_config_modules module_kwargsrhr=rhasattrrr;rappend_model_card_text)r@r7r/r+r-r,r.r0r$r1 model_typerr'rrArs rC_load_converted_modulesz%SparseEncoder._load_converted_moduless$ . .--")!"3!1)!1+.  !2 0  A-@L,>B@ HmH0@0FBHB=B]-@bB  mn&*&?&? %/-%-''@ ' ##w~~'( w' Fv89#;;=    T   :~Ao/   s $****rDct|tjs td|jdvrt d|jd|jdk(r|j d}|j\}}|dk(s|dk(rddd S|j}|j}|dd |d d z }tj|jj}d||z z }||d S) a Calculate sparsity statistics for the given embeddings, including the mean number of active (non-zero) dimensions and the mean sparsity ratio. For a single embedding (1D), the values are for that embedding directly. For a batch of embeddings (2D), they are averaged across the batch. Args: embeddings (torch.Tensor): The embeddings to analyze. Must be a 1D or 2D tensor. Returns: dict[str, float]: Dictionary with ``"active_dims"`` (mean active dimensions) and ``"sparsity_ratio"`` (mean sparsity ratio). Example: :: from sentence_transformers import SparseEncoder model = SparseEncoder("naver/splade-cocondenser-ensembledistil") embeddings = model.encode(["The weather is so nice!", "It's so sunny outside."]) stats = model.sparsity(embeddings) print(stats) # => {'active_dims': 44.0, 'sparsity_ratio': 0.9985584020614624} z!Embeddings must be a torch.Tensor)rr z Expected a 1D or 2D tensor, got D.rrgg?) active_dimssparsity_ratioN) r>r&r TypeErrorndimr; unsqueezeshape to_sparse_csr crow_indicesrfloatitem)rnum_rowsnum_colsrnon_zero_per_rowmean_active_dimsmean_sparsity_ratios rCsparsityzSparseEncoder.sparsitys 6*ell3?@ @ ??& (? ?PPRST T ??a #--a0J'--( q=HM""%   --/ !..0 '+l3B.?? ::&6&<&<&>?DDF!%5%@A,1  rDct|S)a Returns the maximal input sequence length for the model. Longer inputs will be truncated. Returns: int: The maximal input sequence length. Example: :: from sentence_transformers import SparseEncoder model = SparseEncoder("naver/splade-cocondenser-ensembledistil") print(model.max_seq_length) # => 512 )r9max_seq_lengthrs rCr'zSparseEncoder.max_seq_lengths"w%%rDc||d_y)zs Property to set the maximal input sequence length for the model. Longer inputs will be truncated. rN)r'rs rCr'zSparseEncoder.max_seq_length's "'QrDct|S)a/ Property to get the underlying transformers PreTrainedModel instance, if it exists. Note that it's possible for a model to have multiple underlying transformers models, but this property will return the first one it finds in the module hierarchy. Returns: PreTrainedModel or None: The underlying transformers model or None if not found. Example: :: from sentence_transformers import SparseEncoder model = SparseEncoder("naver/splade-v3") # You can now access the underlying transformers model transformers_model = model.transformers_model print(type(transformers_model)) # => )r9transformers_modelrs rCr*z SparseEncoder.transformers_model/s,w))rDcj|jjD]}t|ts|cSy)zVReturns the SpladePooling module if present, or None. Only searches top-level modules.N)r<r=r>r)r@rAs rC_get_splade_poolingz!SparseEncoder._get_splade_poolingGs2mm**, F&-0  rDcj|j}| |jStjdy)a Returns the chunk size of the SpladePooling module, if present. This chunk size is along the sequence length dimension (i.e., number of tokens per chunk). If None, processes the entire sequence at once. Using smaller chunks reduces memory usage but may lower training and inference speed. Default is None. This property is only meaningful for SPLADE-architecture models. For CSR-architecture models (Transformer + Pooling + SparseAutoEncoder), it returns None. Returns: int or None: The chunk size, or None if SpladePooling is not found or chunk_size is not set. Nz6SpladePooling module not found. Cannot get chunk_size.r,rQrcwarning)r@splade_poolings rCsplade_pooling_chunk_sizez'SparseEncoder.splade_pooling_chunk_sizeNs4113  %!,, ,OPrDcb|j}|||_ytjdy)zN Sets the chunk size of the SpladePooling module, if present. Nz6SpladePooling module not found. Cannot set chunk_size.r.)r@rr0s rCr1z'SparseEncoder.splade_pooling_chunk_sizecs- 113  %(-N % NNS TrDc"|js|j}|js|j}|jdk7rtd|jd|jd|jdk7r,td|jdd|jdd|jdk(r||z}nO|jdk(r't j |Dcgc]}||z c}}ntd |jd|j}|jd kD}t j|jd d |f|j||j|j }|Scc}w) a Compute the intersection of two sparse embeddings via element-wise multiplication. For each dimension, the result retains the minimum contribution from both embeddings, keeping only dimensions where both inputs are positive (i.e., shared active dimensions). This is useful for token-level matching and interpretability when combined with :meth:`decode`. Args: embeddings_1 (torch.Tensor): First embedding tensor of shape ``(vocab_size,)``. embeddings_2 (torch.Tensor): Second embedding tensor of shape ``(vocab_size,)`` or ``(batch_size, vocab_size)``. Returns: torch.Tensor: Sparse intersection tensor with the same shape as ``embeddings_2``. Example: :: from sentence_transformers import SparseEncoder model = SparseEncoder("naver/splade-cocondenser-ensembledistil") query_emb = model.encode_query("What is AI?") doc_emb = model.encode_document("Artificial intelligence is a branch of computer science.") shared = model.intersection(query_emb, doc_emb) print(model.decode(shared, top_k=5)) rz-Expected 1D tensor for embeddings_1, but got z shape.rz+Vocab dimension mismatch: embeddings_1 has z, embeddings_2 has r8r z3Expected 1D or 2D tensor for embeddings_2, but got rN)sizer() is_sparser|rr;rr&rcoalescer=sparse_coo_tensorindicesr4r() embeddings_1 embeddings_2 intersection embeddingrs rCr;zSparseEncoder.intersectionns>%%'113L%%'113L    !L\M_M_L``ghi i   b !\%7%7%; ;=l>P>PQS>T=UV$$0$6$6r$:#;1>     !',6L   ! # ;;R^'_Y y(@'_`LRS_SeSeRffmno o$,,. "))+a/ ..  "1k> 2    !+ .""$&&  (`s# F c ||dkrtd|dt|tjst dt ||j dk(}|r|jd}n(|j dk7rtd|j d|js|j}|j}|j}|j}|jdk(r0t|jdDcgc]}g}}|r|dS|S|d|d} }tj ||jd j#} g}d} | D]} | dk(r|j%g|| | | z} | | | | z}| t'|| n| }|| kr!tj(| |\}}||}|} n!tj*| d }| |} ||}|j,j/|j#}|j%t1t3|| j#| | z } |r|dS|Scc}w) a Decode a sparse embedding into (token, weight) pairs sorted by descending weight. Args: embeddings (torch.Tensor): Sparse embedding tensor of shape ``(vocab_size,)`` for a single embedding or ``(batch_size, vocab_size)`` for a batch. top_k (int, optional): Maximum number of top-weighted tokens to return per sample. If ``None``, all non-zero tokens are returned. Must be positive. Defaults to ``None``. Returns: list[tuple[str, float]]: If the input is 1D, a list of ``(token, weight)`` tuples. list[list[tuple[str, float]]]: If the input is 2D, a list (one per sample) of lists of ``(token, weight)`` tuples. rz&top_k must be a positive integer, got r8zExpected torch.Tensor, got rr z#Input tensor must be 1D or 2D, got r) minlengthT) descending)r;r>r&r rrrrr5r|r6r8r=numelrr4bincountrkrrtopkru tokenizerconvert_ids_to_tokensrhzip)r@rtop_kwas_1dr8r=rresultssample_indices token_indices sample_counts start_idxcount sample_values sample_tokens effective_k top_valuestop_idx sorted_idx token_strss rCdecodezSparseEncoder.decodesc"  !EeWANO O*ell39$z:J9KLM MA% #--a0J __ !B:??BSSUVW W###--/J((* $$&""$ <<>Q BG XYHZB[5\Qb5\G5\!'71: 4W 4(/ GAJ ~QRAST[[]  " Ezr""9y5/@AM))i%6GHM/4/@#eU+eKU"&+jj &L# G -g 6 * "]]=TJ -j 9 -j 9 ==m>R>R>TUJ NN4J 0D0D0F GH I  I+ .$wqz00?6]s Ic l|jj}|j}d|d|d|d|d S)Nz## Testing this pull request You can test this pull request before merging by loading the model from this PR with the `revision` argument: ```python from sentence_transformers import zO # NOTE: Update this to the number of your pull request pr_number = 2 model = z( "z5", revision=f"refs/pr/{pr_number}", backend="a", ) # Verify that everything works as expected embeddings = model.encode(["The weather is lovely today.", "It's so sunny outside!", "He drove to the stadium."]) print(embeddings.shape) similarities = model.similarity(embeddings, embeddings) print(similarities) ``` --- *This PR was auto-generated with [`push_to_hub`](https://sbert.net/docs/package_reference/sparse_encoder/SparseEncoder.html#sentence_transformers.sparse_encoder.SparseEncoder.push_to_hub).* )rBrn get_backend)r@repo_id class_namer3s rC_push_to_hub_usage_tipz$SparseEncoder._push_to_hub_usage_tipsZ^^,, ""$#$.,/    YY rDr)$r7rr'zlist[nn.Module] | Noner(rr)zdict[str, str] | Noner*rr+rr,boolr-rr.r[r/bool | str | Noner0dict[str, Any] | Noner$r]r1r]r2z!SparseEncoderModelCardData | Noner3z$Literal['torch', 'onnx', 'openvino']r4zstr | SimilarityFunction | Noner5 int | NonereturnNone) NN NTTFNNNN)rEzlist[TextInput] | TextInputrIrrJrrKintrL bool | NonerMr[rNr[rOr[r(4str | torch.device | list[str | torch.device] | Noner5r^rP9dict[Literal['input', 'output', 'processes'], Any] | NonerQr^rVrr_list[Tensor] | Tensor)r_dict[str, Any])rrgr_r`)r_z2Literal['cosine', 'dot', 'euclidean', 'manhattan'])rzNLiteral['cosine', 'dot', 'euclidean', 'manhattan'] | SimilarityFunction | Noner_r`)rr[r_r`)rr rr r_r )rnpt.NDArray[np.float32]rrhr_r )r_zVCallable[[Tensor | npt.NDArray[np.float32], Tensor | npt.NDArray[np.float32]], Tensor])TNNN) rEzlist[TextInput]rLrcrPrer(rdrQr^r_rf) rstrrrrrrrr_r`)r_r^)NFFNNN)r7rir/r\r+rr-rr,r[r.r[r0r]r$r]r1r]r_&tuple[list[nn.Module], dict[str, Any]])NFFNNNN)r7rir/r\r+rr-rr,r[r.r[r0r]r$r]r1r]rrr_rj)r torch.Tensorr_zdict[str, float])r_rb)rrbr_r`)r_zPreTrainedModel | None)r_zSpladePooling | None)rr^r_r`)r9rkr:rkr_r )rrkrFr^r_z7list[tuple[str, float]] | list[list[tuple[str, float]]])rXrir_ri)*rn __module__ __qualname____doc__rmodel_card_data_classr__annotations__r" _model_card_model_id_placeholderrr:rWr\rUrrpropertyr4setterrrrrrp staticmethodrrr FutureWarningrrrr%r'r*r,r1r;rUrZ __classcell__)rBs@rCrr#sV_B73C$jC8<$.O+O'@$(:;*.4+/!)-*.#'"'#!&#'.226/3=A8?>B&*)4&4( 4  4 ' 4(4!4 444!4,404-4 ;!4"6#4&<'4($)4* +4<4l*#'!)-"&)-!GK&*JN!%F +F  F  F  F ' F  F #'F F EF $F HF F F  F +F P*#'!)-"&)-!GK&*JN!%I +I  I  I  I ' I  I #'I I EI $I HI I I  I +I V*#'!)-"&)-!GK&*JN!%M+M M M  M ' M M#'MMEM$MHMMM M+M^ S ((  \] \  \ \ QQ ss ) ) VZZ 2AX $) _$)$)R*.JNGK!% >3>3'>3H >3 E >3  >3 >3@#0?DUZ 22f. . $"'!&.226/3WW!W! W  W  WW,W0W-W 0W| $"'!&.226/3!%J+J+!J+! J+  J+  J+J+,J+0J+-J+J+ 0J+X7 7 r&&$''**.(%%U&U>">"> >>B=AF1&F1/9F1 @F1PrDr)8 __future__rrrrrcollections.abcrmultiprocessingrtypingrrrnumpyri numpy.typingnptr&r r tqdmr transformersr r transformers.modeling_utilsrtransformers.utilstransformers_loggingtyping_extensionsrsentence_transformers.baser)sentence_transformers.base.modality_typesr"sentence_transformers.base.modulesr2sentence_transformers.sentence_transformer.modulesr/sentence_transformers.sparse_encoder.model_cardr,sentence_transformers.sparse_encoder.modulesrrsentence_transformers.utilrr%sentence_transformers.util.decoratorsr%sentence_transformers.util.similarityr get_loggerrnrcrrSrDrCrsy" $!)) 57>(0?:FVYNCD )  ( ( 2pIprD