fix(embedding): reject incompatible concat sequence mixes

[linhongyu510]

Pull Request / 拉取请求

What does this PR do? / 这个 PR 做了什么？

SequenceFeature(pooling="concat") preserves the sequence axis, so its embedding has shape [B, 1, L, D]. Sparse and mean/sum-pooled sequence embeddings have shape [B, 1, D]. Passing both kinds in one EmbeddingLayer call currently reaches torch.cat and fails with:

RuntimeError: Tensors must have same number of dimensions: got 3 and 4

This PR:

• validates the incompatible feature combination before embedding lookup;
• raises an actionable ValueError naming both concat-pooled and incompatible features;
• preserves valid concat-only output [B, H, L, D];
• preserves mean/sum sequence plus sparse behavior;
• preserves concat sequence plus dense flattening when squeeze_dim=True;
• documents the contract in the English and Chinese feature guides.

The change intentionally does not implement dynamic embedding-dimension concatenation from the original issue title.

Type of Change / 变更类型

• 🐛 Bug fix / Bug修复
• ✨ New model/feature / 新模型/功能
• 📝 Documentation / 文档
• 🔧 Maintenance / 维护

Related Issues / 相关 Issues

Related to #226.

How to Test / 如何测试

Environment:

• macOS arm64
• repository dependency declaration from pyproject.toml
• Python 3.13.15 with PyTorch 2.9.1
• Python 3.9.25 with PyTorch 2.8.0 for the targeted regression file

# Targeted regression tests on Python 3.13 and Python 3.9
pytest tests/test_embedding_layer.py -q
# 5 passed on each interpreter

# Related matching and MIND tests
pytest tests/test_embedding_layer.py tests/test_e2e_matching.py tests/test_mind_dynamic_interest.py -q
# 8 passed, 9 skipped by existing model markers

# Broad local suite, excluding serving/Milvus integration
SKIP_MILVUS_TESTS=1 pytest -c config/pytest.ini tests/ -q --ignore=tests/test_serving.py
# 78 passed, 45 skipped

# CI-equivalent formatting/lint for changed Python files
isort --check-only --profile black torch_rechub/basic/layers.py tests/test_embedding_layer.py
yapf --diff --style='{based_on_style: google, column_limit: 248, join_multiple_lines: false, split_all_comma_separated_values: true, split_before_logical_operator: true, dedent_closing_brackets: true, align_closing_bracket_with_visual_indent: true, indent_width: 4}' torch_rechub/basic/layers.py tests/test_embedding_layer.py
flake8 --max-line-length=248 --extend-ignore=E203,W503,E501,E722,E402,F821,F523,E711,E741,F401,E265,C901,E301,E305,W293,E261,W291,W292,E111,E117,F841,E302 --max-complexity=30 torch_rechub/basic/layers.py tests/test_embedding_layer.py
git diff --check

The broad suite skipped tests that explicitly require uninstalled optional ONNX or Transformers dependencies, plus existing complex-model skips. No executed test failed. The repository CI remains authoritative for the complete optional-dependency matrix and cross-platform checks.

Checklist / 检查清单

• Code follows project style / 代码遵循项目风格
• Added targeted regression tests / 添加了针对性回归测试
• Updated English and Chinese documentation / 同步更新中英文文档
• Verified no open competing PR or newer implementation before submission / 提交前确认无开放竞争 PR 或更新实现