From ef4f0c42977d1e45e7ede69b2f52718a05c33465 Mon Sep 17 00:00:00 2001 From: Jennifer Hamon Date: Fri, 19 Jul 2024 12:51:36 -0400 Subject: [PATCH] Readme changes for v5 release. (#371) ## Problem Need to update README with content about deletion protection and inference. ## Solution Update examples ## Type of Change - [x] Non-code change (docs, etc) --- README.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 75 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index e6a6ae31..44446857 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,22 @@ For more information, see the docs at https://www.pinecone.io/docs/ ## Documentation -- If you are upgrading from a `2.2.x` version of the client, check out the [**v3 Migration Guide**](https://canyon-quilt-082.notion.site/Pinecone-Python-SDK-v3-0-0-Migration-Guide-056d3897d7634bf7be399676a4757c7b#a21aff70b403416ba352fd30e300bce3). - [**Reference Documentation**](https://sdk.pinecone.io/python/index.html) +### Upgrading your client + +#### Upgrading from `4.x` to `5.x` + +As part of an overall move to stop exposing generated code in the package's public interface, an obscure configuration property (`openapi_config`) was removed in favor of individual configuration options such as `proxy_url`, `proxy_headers`, and `ssl_ca_certs`. All of these properties were available in v3 and v4 releases of the SDK, with deprecation notices shown to affected users. + +It is no longer necessary to install a separate plugin, `pinecone-plugin-inference`, to try out the [Inference API](https://docs.pinecone.io/guides/inference/understanding-inference); that plugin is now installed by default in the v5 SDK. See [usage instructions below](#inference-api). + +#### Older releases + +- **Upgrading to `4.x`** : For this upgrade you are unlikely to be impacted by breaking changes unless you are using the `grpc` extras (see install steps below). Read full details in these [v4 Release Notes](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v4.0.0). + +- **Upgrading to `3.x`**: Many things were changed in the v3 client to pave the way for Pinecone's new Serverless index offering. These changes are covered in detail in the [**v3 Migration Guide**](https://canyon-quilt-082.notion.site/Pinecone-Python-SDK-v3-0-0-Migration-Guide-056d3897d7634bf7be399676a4757c7b#a21aff70b403416ba352fd30e300bce3). Serverless indexes are only available in `3.x` release versions or greater. + ### Example code Many of the brief examples shown in this README are using very small vectors to keep the documentation concise, but most real world usage will involve much larger embedding vectors. To see some more realistic examples of how this client can be used, explore some of our many Jupyter notebooks in the [examples](https://github.com/pinecone-io/examples) repository. @@ -34,10 +47,10 @@ pip3 install pinecone-client pip3 install "pinecone-client[grpc]" # Install a specific version -pip3 install pinecone-client==3.0.0 +pip3 install pinecone-client==5.0.0 # Install a specific version, with grpc extras -pip3 install "pinecone-client[grpc]"==3.0.0 +pip3 install "pinecone-client[grpc]"==5.0.0 ``` ### Installing with poetry @@ -50,10 +63,10 @@ poetry add pinecone-client poetry add pinecone-client --extras grpc # Install a specific version -poetry add pinecone-client==3.0.0 +poetry add pinecone-client==5.0.0 # Install a specific version, with grpc extras -poetry add pinecone-client==3.0.0 --extras grpc +poetry add pinecone-client==5.0.0 --extras grpc ``` ## Usage @@ -197,6 +210,7 @@ pc.create_index( name='my-index', dimension=1536, metric='euclidean', + deletion_protection='enabled', spec=ServerlessSpec( cloud='aws', region='us-west-2' @@ -217,6 +231,7 @@ pc.create_index( name="example-index", dimension=1536, metric="cosine", + deletion_protection='enabled', spec=PodSpec( environment='us-west-2', pod_type='p1.x1' @@ -275,7 +290,7 @@ index_description = pc.describe_index("example-index") ## Delete an index -The following example deletes the index named `example-index`. +The following example deletes the index named `example-index`. Only indexes which are not protected by deletion protection may be deleted. ```python from pinecone import Pinecone @@ -298,6 +313,26 @@ new_number_of_replicas = 4 pc.configure_index("example-index", replicas=new_number_of_replicas) ``` +## Configuring deletion protection + +If you would like to enable deletion protection, which prevents an index from being deleted, the `configure_index` method also handles that via an optional `deletion_protection` keyword argument. + +```python +from pinecone import Pinecone + +pc = Pinecone(api_key='<>') + +# To enable deletion protection +pc.configure_index("example-index", deletion_protection='enabled') + +# Disable deletion protection +pc.configure_index("example-index", deletion_protection='disabled') + +# Call describe index to verify the configuration change has been applied +desc = pc.describe_index("example-index") +print(desc.deletion_protection) +``` + ## Describe index statistics The following example returns statistics about the index `example-index`. @@ -514,6 +549,40 @@ pc = Pinecone(api_key='<>') pc.delete_collection("example-collection") ``` +# Inference API + +The Pinecone SDK now supports creating embeddings via the [Inference API](https://docs.pinecone.io/guides/inference/understanding-inference). + +```python +from pinecone import Pinecone + +pc = Pinecone(api_key="YOUR_API_KEY") +model = "multilingual-e5-large" + +# Embed documents +text = [ + "Turkey is a classic meat to eat at American Thanksgiving.", + "Many people enjoy the beautiful mosques in Turkey.", +] +text_embeddings = pc.inference.embed( + model=model, + inputs=text, + parameters={"input_type": "passage", "truncate": "END"}, +) + +# Upsert documents into Pinecone index + +# Embed a query +query = ["How should I prepare my turkey?"] +query_embeddings = pc.inference.embed( + model=model, + inputs=query, + parameters={"input_type": "query", "truncate": "END"}, +) + +# Send query to Pinecone index to retrieve similar documents +``` + # Contributing If you'd like to make a contribution, or get setup locally to develop the Pinecone python client, please see our [contributing guide](https://github.com/pinecone-io/pinecone-python-client/blob/main/CONTRIBUTING.md)