Install & Compatibility
Where this runs
tested against v0.11.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.13
✕ build_error
✕ build_error
114MB installed
● package 114MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenAIEncoder
✓ from pinecone_text import OpenAIEncoder
✗ from pinecone_text import OpenAIEncoder
This quickstart demonstrates how to initialize the `OpenAIEncoder` and use it to generate dense vector embeddings for both documents and queries. It highlights the necessity of setting the `OPENAI_API_KEY` environment variable.
import os
from pinecone_text.dense import OpenAIEncoder
# Ensure OPENAI_API_KEY is set in your environment
# For quick testing, you can uncomment and set it directly, but prefer environment variables
# os.environ["OPENAI_API_KEY"] = "YOUR_OPENAI_API_KEY"
if not os.environ.get("OPENAI_API_KEY"):
print("Error: OPENAI_API_KEY environment variable not set.")
print("Please set it or uncomment the line above for testing.")
else:
try:
encoder = OpenAIEncoder() # Defaults to 'text-embedding-3-small'
documents = [
"The quick brown fox jumps over the lazy dog",
"Artificial intelligence is transforming industries"
]
queries = [
"Who jumped over the lazy dog?",
"What is AI doing?"
]
document_vectors = encoder.encode_documents(documents)
query_vectors = encoder.encode_queries(queries)
print(f"Encoded document 1 vector (first 5 elements): {document_vectors[0][:5]}...")
print(f"Encoded query 1 vector (first 5 elements): {query_vectors[0][:5]}...")
except Exception as e:
print(f"An error occurred during encoding: {e}")
Debug
Known issues
gotchaThe `pinecone-text` library is currently in 'public preview' ('Beta'). This means its API or behavior may change in future updates.fixMonitor official documentation and release notes for breaking changes and updates. Test thoroughly when upgrading.
affects: 0.1.0 - 0.11.0
breakingThe main Pinecone Python SDK was renamed from `pinecone-client` to `pinecone` in version 5.1.0. If you are migrating or have existing projects, ensure you update your dependencies to `pinecone` to get the latest features and avoid conflicts.fixRemove `pinecone-client` from your `requirements.txt` or `pyproject.toml` and add `pinecone` instead. For example, `pip uninstall pinecone-client && pip install pinecone`.
affects: pinecone-client < 5.1.0
gotchaThe `BM25Encoder` currently supports only static document frequency. This means precomputed document frequency values are fixed and do not dynamically update when new documents are added to a collection.fixBe aware of this limitation when building systems where document frequencies are expected to change frequently. Consider re-fitting the BM25 model if the corpus changes significantly, or use alternative sparse encoding methods.
affects: 0.1.0 - 0.11.0
breakingUsing SPLADE and Sentence Transformer models with `pinecone-text` is not currently supported on Python 3.12 due to compatibility issues with PyTorch.fixUse Python versions 3.9, 3.10, or 3.11 if you need to use SPLADE or Sentence Transformer models. Check `pinecone-text` release notes for future Python 3.12 compatibility updates.
affects: 0.1.0 - 0.11.0 with Python 3.12
gotchaWhen using `OpenAIEncoder` or `AzureOpenAIEncoder`, the corresponding API key (e.g., `OPENAI_API_KEY`) must be set as an environment variable before the encoder is initialized.fixSet the `OPENAI_API_KEY` (or `AZURE_OPENAI_API_KEY` and other Azure-specific variables for `AzureOpenAIEncoder`) environment variable before importing and instantiating the encoder class.
affects: 0.1.0 - 0.11.0
Upgrade
Version history
0.11.0latest on PyPI · released Aug 11, 2025
Audit
Dependencies
pineconerequiredRequired for interacting with the Pinecone vector database, as pinecone-text provides embedding utilities that are typically used to prepare data for Pinecone indexes.
openaioptionalRequired if using the `OpenAIEncoder` for dense vector generation.
torchoptionalUnderlying dependency for SPLADE and Sentence Transformer models; incompatibility issues exist with Python 3.12.