ChLSSKJr SSKrSSKrSSKJr SSKJr SSK J r J r SSK Jr SSKJr SSKJr SS KJrJr \R,"\5r"S S \5r\rg!\a SSK Jr NPf=f) ) annotationsN)Path)Self)Tensornn)logging) InputModule)Module)import_from_string load_dir_pathcH^\rSrSr%S1rSS/rS\S'SrSSU4Sjjjr\ SSS jj5r SSS jjr SS jr SSS jjr SSS jjr\ SSSjj5r\S5r\SSj5r\R&SSj5rSrU=r$)Routertask default_routeallow_empty_keyz list[str] config_keyszrouter_config.jsonc >[TU]5 Ub[U5S:Xa [S5eUb-X!;a([SUS[ UR 5535e[ R"UR5VVs0sHupEU[ R"U6_M snn5Ul U(a%Uc"[[UR 555nX l X0lgs snnf)a This model allows to create asymmetric SentenceTransformer models that apply different modules depending on the specified route, such as "query" or "document". Especially useful for models that have different encoders for queries and documents. Notably, the ``task`` argument of ``model.encode`` can be used to specify which route to use, and ``model.encode_query`` and ``model.encode_document`` are shorthands for using ``task="query"`` and ``task="document"``, respectively. These methods also optionally apply ``prompts`` specific to queries or documents. .. note:: When training models with the :class:`~sentence_transformers.models.Router` module, you must use the ``router_mapping`` argument in the :class:`~sentence_transformers.training_args.SentenceTransformerTrainingArguments` or :class:`~sentence_transformers.sparse_encoder.training_args.SparseEncoderTrainingArguments` to map the training dataset columns to the correct route ("query" or "document"). For example, if your training dataset(s) have ``["question", "positive", "negative"]`` columns, then you can use the following mapping:: args = SparseEncoderTrainingArguments( ..., router_mapping={ "question": "query", "positive": "document", "negative": "document", } ) Additionally, it is common to use a different learning rate for the different routes. For this, you should use the ``learning_rate_mapping`` argument in the :class:`~sentence_transformers.training_args.SentenceTransformerTrainingArguments` or :class:`~sentence_transformers.sparse_encoder.training_args.SparseEncoderTrainingArguments` to map parameter patterns to their learning rates. For example, if you want to use a learning rate of ``1e-3`` for an SparseStaticEmbedding module and ``2e-5`` for the rest of the model, you can do this:: args = SparseEncoderTrainingArguments( ..., learning_rate=2e-5, learning_rate_mapping={ r"SparseStaticEmbedding\.*": 1e-3, } ) In the below examples, the ``Router`` model is used to create asymmetric models with different encoders for queries and documents. In these examples, the "query" route is efficient (e.g., using SparseStaticEmbedding), while the "document" route uses a more complex model (e.g. a Transformers module). This allows for efficient query encoding while still using a powerful document encoder, but the combinations are not limited to this. Example: :: from sentence_transformers import SentenceTransformer from sentence_transformers.models import Router, Normalize # Use a regular SentenceTransformer for the document embeddings, and a static embedding model for the query embeddings document_embedder = SentenceTransformer("mixedbread-ai/mxbai-embed-large-v1") query_embedder = SentenceTransformer("sentence-transformers/static-retrieval-mrl-en-v1") router = Router.for_query_document( query_modules=list(query_embedder.children()), document_modules=list(document_embedder.children()), ) normalize = Normalize() # Create an asymmetric model with different encoders for queries and documents model = SentenceTransformer( modules=[router, normalize], ) # ... requires more training to align the vector spaces # Use the query & document routes query_embedding = model.encode_query("What is the capital of France?") document_embedding = model.encode_document("Paris is the capital of France.") :: from sentence_transformers.models import Router from sentence_transformers.sparse_encoder import SparseEncoder from sentence_transformers.sparse_encoder.models import MLMTransformer, SparseStaticEmbedding, SpladePooling # Load an asymmetric model with different encoders for queries and documents doc_encoder = MLMTransformer("opensearch-project/opensearch-neural-sparse-encoding-doc-v3-distill") router = Router.for_query_document( query_modules=[ SparseStaticEmbedding.from_json( "opensearch-project/opensearch-neural-sparse-encoding-doc-v3-distill", tokenizer=doc_encoder.tokenizer, frozen=True, ), ], document_modules=[ doc_encoder, SpladePooling(pooling_strategy="max", activation_function="log1p_relu"), ], ) model = SparseEncoder(modules=[router], similarity_fn_name="dot") query = "What's the weather in ny now?" document = "Currently New York is rainy." query_embed = model.encode_query(query) document_embed = model.encode_document(document) sim = model.similarity(query_embed, document_embed) print(f"Similarity: {sim}") # Visualize top tokens for each text top_k = 10 print(f"Top tokens {top_k} for each text:") decoded_query = model.decode(query_embed, top_k=top_k) decoded_document = model.decode(document_embed) for i in range(min(top_k, len(decoded_query))): query_token, query_score = decoded_query[i] doc_score = next((score for token, score in decoded_document if token == query_token), 0) if doc_score != 0: print(f"Token: {query_token}, Query score: {query_score:.4f}, Document score: {doc_score:.4f}") ''' Similarity: tensor([[11.1105]], device='cuda:0') Top tokens 10 for each text: Token: ny, Query score: 5.7729, Document score: 0.8049 Token: weather, Query score: 4.5684, Document score: 0.9710 Token: now, Query score: 3.5895, Document score: 0.4720 Token: ?, Query score: 3.3313, Document score: 0.0286 Token: what, Query score: 2.7699, Document score: 0.0787 Token: in, Query score: 0.4989, Document score: 0.0417 ''' Note: These models are not necessarily stronger than non-asymmetric models. Rudimentary experiments indicate that non-Router models perform better in many cases. Args: sub_modules: Mapping of route keys to lists of modules. Each key corresponds to a specific task type, often "query" or "document", and the list contains the modules to be applied for that task type. default_route: The default route to use if no task type is specified. If None, an exception will be thrown if no task type is specified. If ``allow_empty_key`` is True, the first key in sub_modules will be used as the default route. Defaults to None. allow_empty_key: If True, allows the default route to be set to the first key in `sub_modules` if ``default_route`` is None. Defaults to True. Nrz&The routes dictionary cannot be empty.zDefault route 'z' not found in route keys: )super__init__len ValueErrorlistkeysr ModuleDictitems Sequential sub_modulesnextiterrr)selfrrr route_namemodules __class__s [/var/www/html/shao/venv/lib/python3.13/site-packages/sentence_transformers/models/Router.pyrRouter.__init__s`   #k"2a"7EF F  $)I}o=XY]^i^n^n^pYqXrst t==LWL]L]L_ `L_5HZZ0 0L_ `  }4 k&6&6&8!9:M*. asC% c(U"XS.U=(d SUS9$)aI Creates a Router model specifically for query and document modules, allowing convenient usage via `model.encode_query` and `model.encode_document`. Args: query_modules: List of modules to be applied for the "query" task type. document_modules: List of modules to be applied for the "document" task type. default_route: The default route to use if no task type is specified. If None, an exception will be thrown if no task type is specified. If ``allow_empty_key`` is True, the first key in sub_modules will be used as the default route. Defaults to None. allow_empty_key: If True, allows the default route to be set to the first key in `sub_modules` if ``default_route`` is None. Defaults to True. Returns: Router: An instance of the Router model with the specified query and document modules. )querydocumentr))rrr)cls query_modulesdocument_modulesrrs r%for_query_documentRouter.for_query_documents"0"/N'5:+  c UcURSUR5nUc'UR(a [S5e[S5eX R;a2[SUS[ URR 5535eX#S'URUHSnUR5VVs0sH+upV[US5(dMXTR;dM)XV_M- nnnU"U40UD6nMU U$s snnf)NrvYou must provide a `router_mapping` argument on the training arguments, or set a default route in the `Router` module.kYou must provide a `task` argument when calling this method, or set a default route in the `Router` module.No route found for task type ''. Available routes: forward_kwargs) getrtrainingrrrrrhasattrr6)r!featuresrkwargsmodulekeyvalue module_kwargss r%forwardRouter.forwards <<<(:(:;D <}} E !E '' '06KDQUQaQaQfQfQhLiKjk v&&t,F#),,."0JC6#349<@U@U9U "0  h8-8H - s4C7 C7C7cURR5H:n[U5H(n[US5(dMUR 5s s $ M< g)N get_sentence_embedding_dimension)rvaluesreversedr9rC)r!rr<s r%rC'Router.get_sentence_embedding_dimensionsL++224K";/6#EFF!BBDD05r0c R0n0n0nURR5Hupx/Xg'[U5HhupUSU S[U 5R3n XU '[U 5R S[U 5R3X['XgR U 5 Mj M UR5HYup[RRU[U 55n [R"U SS9 U R"U 4SU0UD6 M[ [[RRXR5SSS9n [ R""UUUR%5S .U S S 9 SSS5 g![a U RU 5 Mf=f!,(df  g=f) N_.T)exist_oksafe_serializationwutf8)encoding)types structure parameters)indent)rr enumeratetype__name__ __module__appendospathjoinstrmakedirssave TypeErroropenconfig_file_namejsondumpget_config_dict)r! output_pathrKr; model_lookup model_typesmodel_structurenamemodels module_idxmodelmodel_id model_pathfOuts r%r^ Router.saves   ,,224LD$&O !%.v%6! "V1ZL$u+2F2F1GH).X&+/;+A+A*B!DKDXDXCY(Z %%,,X6 &75 ,113OHk3x=AJ KK T 2 ' :W:LWPVW 4"'',,{,A,ABCRX Y]a II(!0"&"6"6"8  Z Y  ' :& 'Z Ys9E6)F6FF F&c *[US[5(aRUc<[SU55n[U5S:a [ S5eUR 5nUVs/sHoUUPM nnUc UR nUc'UR(a [ S5e[ S5eX R;a2[ SUS[URR5535eURUSnUR"U40UD6nX'S 'U$s snf) z-Tokenizes a text and maps tokens to token-idsrc3N# UHoR5Ho"v M M g7fN)r).0textr=s r% "Router.tokenize..$sIEDYY[cC[CEs#%zYou cannot pass a list of dictionaries with different task types. Please ensure all dictionaries have the same task type key, or pass a single `task` argument.r2r3r4r5r) isinstancedictsetrrpoprr8rrrtokenize)r!textsrr;tasksru input_module tokenizeds r%r}Router.tokenizes0 eAh % %|IEIIu:>$xyy{-22ED$ZEE2 <%%D <}} E !E '' '06KDQUQaQaQfQfQhLiKjk ''-a0  ))%:6:  &/3s Dc XUUUUS.nUR"S XS.UD6n U (dUR"S USUS.UD6n 0n U SR5HCup[U 5n U R"U4S[ X+5R 50UDUD6nXU 'ME 0nU SR5H*unn/UU'UHn UURX5 M M, U"U40U SD6nU$![ a9 [S U[ X+5R 5S.UD6nU RU5nNf=f) N)token cache_folderrevisionlocal_files_only)model_name_or_path subfolderz config.json)rconfig_filenamerrOrrPrQr*) load_configrr loadras_posixr_r rX)r+rrrrrrr; hub_kwargsconfigr#rm model_type module_classr< local_pathrhkey_name models_listrls r%r Router.loadFs( 0  j4Fj_ij__#5}`imwF$*7O$9$9$; H#5j#AL 7%**&26y2K2T2T2VZdhn!'H %<%+K%8%>%>%@ !Hk(*OH %')001BC(&A Ohas_max_seq_length_keysr=rjrs r%rrs#%++113KCv'&)-=>>'..s34 & '1 , NNO P *C(,(8(8(=a(@L*/ '+r0)rrr)NT)rzdict[str, list[Module]]r str | NonerboolreturnNone) r, list[Module]r-rrrrrrrrs)r:dict[str, Tensor]rrrr)rint)T)rer\rKr)r~z!list[str] | list[tuple[str, str]]rr)NNNF)rr\rr\rzbool | str | Nonerrrrrrrr)rr)rVrW __qualname____firstlineno__r6r__annotations__rar classmethodr.r@rCr^r}rpropertyrrsetter__static_attributes__ __classcell__)r$s@r%rrsfXN-/@AKA+os^/2^/CM^/gk^/ ^/^/@ %) $  # ' "       :<B%N#'#'#!&+++! + ! +  ++ ++Z((" 0 0r0r) __future__rrbrYpathlibrtypingr ImportErrortyping_extensionstorchrrtransformers.utilsr(sentence_transformers.models.InputModuler #sentence_transformers.models.Moduler sentence_transformers.utilr r get_loggerrVrrAsymr*r0r%rse" '&@6H   H %G0[G0V q '&'sA A-,A-