Skip to content

Commit

Permalink
Python: Env sample (#6711)
Browse files Browse the repository at this point in the history 
### Motivation and Context

<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->
Clarify the names and uses of the environment variables and pydantic
settings.

### Description

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [x] The code builds clean without any errors or warnings
- [x] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [x] All unit tests pass, and I have added new tests where possible
- [x] I didn't break anyone 😄
  • Loading branch information
@eavanvalkenburg
eavanvalkenburg committed Jun 14, 2024
1 parent 17a2e41 commit 1cc6464
Show file tree
Hide file tree
Showing 5 changed files with 227 additions and 1 deletion.
1 change: 1 addition & 0 deletions python/samples/concepts/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,5 @@ This section contains code snippets that demonstrate the usage of Semantic Kerne
| PromptTemplates | Using [`Templates`](https://github.com/microsoft/semantic-kernel/blob/main/python/semantic_kernel/prompt_template/prompt_template_base.py) with parametrization for `Prompt` rendering |
| RAG | Different ways of `RAG` (Retrieval-Augmented Generation) |
| Search | Using search services information |
| Setup | How to setup environment variables for Semantic Kernel |
| TextGeneration | Using [`TextGeneration`](https://github.com/microsoft/semantic-kernel/blob/main/python/semantic_kernel/connectors/ai/text_completion_client_base.py) capable service with models |
75 changes: 75 additions & 0 deletions python/samples/concepts/setup/ALL_SETTINGS.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
## AI Service Settings used across SK:

| Service | Class | Constructor Settings | Environment Variable | Required? | Settings Class |
| --- | --- | --- | --- | --- | --- |
OpenAI | [OpenAIChatCompletion](../../../semantic_kernel/connectors/ai/open_ai/services/open_ai_chat_completion.py) | | | | [OpenAISettings](../../../semantic_kernel/connectors/ai/open_ai/settings/open_ai_settings.py)
| | | ai_model_id | OPENAI_CHAT_MODEL_ID | Yes
| | | api_key | OPENAI_API_KEY | Yes
| | | org_id | OPENAI_ORG_ID | No
| | [OpenAITextCompletion](../../../semantic_kernel/connectors/ai/open_ai/services/open_ai_text_completion.py)
| | | ai_model_id | OPENAI_TEXT_MODEL_ID | Yes
| | | api_key | OPENAI_API_KEY | Yes
| | | org_id | OPENAI_ORG_ID | No
| | [OpenAITextEmbedding](../../../semantic_kernel/connectors/ai/open_ai/services/open_ai_text_embedding.py)
| | | ai_model_id | OPENAI_EMBEDDING_MODEL_ID | Yes
| | | api_key | OPENAI_API_KEY | Yes
| | | org_id | OPENAI_ORG_ID | No
Azure OpenAI | [AzureOpenAIChatCompletion](../../../semantic_kernel/connectors/ai/open_ai/services/azure_chat_completion.py) | | | | [AzureOpenAISettings](../../../semantic_kernel/connectors/ai/open_ai/settings/azure_open_ai_settings.py)
| | | deployment_name | AZURE_OPENAI_CHAT_DEPLOYMENT_NAME | Yes
| | | api_key | AZURE_OPENAI_API_KEY | Yes
| | | endpoint | AZURE_OPENAI_ENDPOINT | Yes
| | | api_version | AZURE_OPENAI_API_VERSION | Yes
| | | base_url | AZURE_OPENAI_BASE_URL | Yes
| | [AzureOpenAITextCompletion](../../../semantic_kernel/connectors/ai/open_ai/services/azure_text_completion.py)
| | | deployment_name | AZURE_OPENAI_TEXT_DEPLOYMENT_NAME | Yes
| | | api_key | AZURE_OPENAI_API_KEY | Yes
| | | endpoint | AZURE_OPENAI_ENDPOINT | Yes
| | | api_version | AZURE_OPENAI_API_VERSION | Yes
| | | base_url | AZURE_OPENAI_BASE_URL | Yes
| | [AzureOpenAITextEmbedding](../../../semantic_kernel/connectors/ai/open_ai/services/azure_text_embedding.py)
| | | deployment_name | AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME | Yes
| | | api_key | AZURE_OPENAI_API_KEY | Yes
| | | endpoint | AZURE_OPENAI_ENDPOINT | Yes
| | | api_version | AZURE_OPENAI_API_VERSION | Yes
| | | base_url | AZURE_OPENAI_BASE_URL | Yes

## Memory Service Settings used across SK:

| Service | Class | Constructor Settings | Environment Variable | Required? | Settings Class |
| --- | --- | --- | --- | --- | --- |
AstraDB | [AstraDBMemoryService](../../../semantic_kernel/connectors/memory/astradb/astradb_memory_store.py) | | | | [AstraDBSettings](../../../semantic_kernel/connectors/memory/astradb/astradb_settings.py)
| | | app_token | ASTRADB_APP_TOKEN | Yes
| | | db_id | ASTRADB_DB_ID | Yes
| | | region | ASTRADB_REGION | Yes
| | | keyspace | ASTRADB_KEYSPACE | Yes
Azure AI Search | [AzureAISearchMemoryService](../../../semantic_kernel/connectors/memory/azure_cognitive_search/azure_cognitive_search_memory_store.py) | | | | [AzureAISearchSettings](../../../semantic_kernel/connectors/memory/azure_cognitive_search/azure_ai_search_settings.py)
| | | api_key | AZURE_AI_SEARCH_API_KEY | No
| | | endpoint | AZURE_AI_SEARCH_ENDPOINT | Yes
| | | index_name | AZURE_AI_SEARCH_INDEX_NAME | No
Azure Cosmos DB | [AzureCosmosDBMemoryService](../../../semantic_kernel/connectors/memory/azure_cosmosdb/azure_cosmos_db_memory_store.py) | | | | [AzureCosmosDBSettings](../../../semantic_kernel/connectors/memory/azure_cosmosdb/azure_cosmosdb_settings.py)
| | | api | AZURE_COSMOS_DB_API | No
| | | connection_string | AZURE_COSMOS_DB_CONNECTION_STRING or AZCOSMOS_CONNSTR | No
Mongo DB Atlas | [MongoDBAtlasMemoryService](../../../semantic_kernel/connectors/memory/mongodb_atlas/mongodb_atlas_memory_store.py) | | | | [MongoDBAtlasSettings](../../../semantic_kernel/connectors/memory/mongodb_atlas/mongodb_atlas_settings.py)
| | | connection_string | MONGODB_ATLAS_CONNECTION_STRING | Yes
| | | database_name | MONGODB_ATLAS_DATABASE_NAME | No
| | | index_name | MONGODB_ATLAS_INDEX_NAME | No
Pinecone | [PineconeMemoryService](../../../semantic_kernel/connectors/memory/pinecone/pinecone_memory_store.py) | | | | [PineconeSettings](../../../semantic_kernel/connectors/memory/pinecone/pinecone_settings.py)
| | | api_key | PINECONE_API_KEY | Yes
Postgres | [PostgresMemoryService](../../../semantic_kernel/connectors/memory/postgres/postgres_memory_store.py) | | | | [PostgresSettings](../../../semantic_kernel/connectors/memory/postgres/postgres_settings.py)
| | | connection_string | POSTGRES_CONNECTION_STRING | Yes
Redis | [RedisMemoryService](../../../semantic_kernel/connectors/memory/redis/redis_memory_store.py) | | | | [RedisSettings](../../../semantic_kernel/connectors/memory/redis/redis_settings.py)
| | | connection_string | REDIS_CONNECTION_STRING | Yes
Weaviate | [WeaviateMemoryService](../../../semantic_kernel/connectors/memory/weaviate/weaviate_memory_store.py) | | | | [WeaviateSettings](../../../semantic_kernel/connectors/memory/weaviate/weaviate_settings.py)
| | | url | WEAVIATE_URL | No
| | | api_key | WEAVIATE_API_KEY | No
| | | use_embed | WEAVIATE_USE_EMBED | No

## Other settings used:

| Service | Class | Constructor Settings | Environment Variable | Required? | Settings Class |
| --- | --- | --- | --- | --- | --- |
Bing | [BingSearch](../../../semantic_kernel/connectors/search_engine/bing_connector.py) | | | | [BingSettings](../../../semantic_kernel/connectors/search_engine/bing_connector_settings.py)
| | | api_key | BING_API_KEY | No
| | | custom_config | BING_CUSTOM_CONFIG | No
Azure Container Apps Sessions | [ACASessionsPlugin](../../../semantic_kernel/core_plugins/sessions_python_tool/sessions_python_plugin.py) | | | | [ACASessionsSettings](../../../semantic_kernel/core_plugins/sessions_python_tool/sessions_python_settings.py)
| | | pool_management_endpoint | ACA_POOL_MANAGEMENT_ENDPOINT | Yes
75 changes: 75 additions & 0 deletions python/samples/concepts/setup/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Using environment variables to setup Semantic Kernel

Semantic Kernel allows you multiple ways to setup your connectors. This guide shows that for OpenAI Connectors.

After installing the semantic-kernel package, you can try these out.

## From environment settings
using this method will try to find the required settings in the environment variables
this is done using pydantic settings, see the full docs of that here: https://docs.pydantic.dev/latest/concepts/pydantic_settings/#usage
We use a prefix for all the settings and then have names defined in the OpenAISettings class
for OpenAI that is OPENAI_ as the prefix, with the following settings:

- api_key (`OPENAI_API_KEY`): OpenAI API key, see https://platform.openai.com/account/api-keys
- org_id (`OPENAI_ORG_ID`): This is usually optional unless your account belongs to multiple organizations.
- chat_model_id (`OPENAI_CHAT_MODEL_ID`): The OpenAI chat model ID to use, for example, gpt-3.5-turbo or gpt-4,
this variable is used in the OpenAIChatCompletion class and get's passed to the ai_model_id there.
- text_model_id (`OPENAI_TEXT_MODEL_ID`): The OpenAI text model ID to use, for example, gpt-3.5-turbo-instruct,
this variable is used in the OpenAITextCompletion class and get's passed to the ai_model_id there.
- embedding_model_id (`OPENAI_EMBEDDING_MODEL_ID`): The embedding model ID to use, for example, text-embedding-ada-002,
this variable is used in the OpenAITextEmbedding class and get's passed to the ai_model_id there.

```python
import os

from pydantic import ValidationError

from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

try:
# when nothing is passed to the constructor,
# it will use the above environment variable names to find the required settings,
# in this case it will only fail if the OPENAI_CHAT_MODEL_ID and OPENAI_API_KEY are not found
service = OpenAIChatCompletion(service_id="openai_chat_service")
except ValidationError as e:
print(e)
```

## From a .env file
when you want to store and use your settings from a specific file (any file as long as it is in the .env format) you can pass the path to the file to the constructor this will still look at the same names of the settings as above, but will try to load them from the file

```python
try:
# this will try to load the settings from the file at the given path
service = OpenAIChatCompletion(service_id="openai_chat_service", env_file_path="path/to/env_file")
except ValidationError as e:
print(e)
```

## From a different value
if you want to pass the settings yourself, you can do that by passing the values to the constructor this will ignore the environment variables and the .env file in this case our API_KEY is stored in a env variable called MY_API_KEY_VAR_NAME if using a file for this value, then we first need run the following code to load the .env file from the same folder as this file:

```python
from dotenv import load_dotenv
dotenv_path = os.path.join(os.path.dirname(__file__), '.env')
load_dotenv(dotenv_path)
```

After that pass the value directly to the constructor as shown below we can also fix another value, in this case the ai_model_id, which becomes chat_model_id in the settings, fixed to gpt-4o

```python
try:
# this will use the given values as the settings
api_key = os.getenv("MY_API_KEY_VAR_NAME")
service = OpenAIChatCompletion(
service_id="openai_chat_service",
api_key=api_key,
ai_model_id="gpt-4o",
)
except ValidationError as e:
print(e)
```

## One final note:

It is a convention that env settings are setup with all caps, and with underscores between words the loader that we use is case insensitive, so you can use any case you want in your env variables but it is a good practice to follow the convention and use all caps.
75 changes: 75 additions & 0 deletions python/samples/concepts/setup/openai_env_setup.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Copyright (c) Microsoft. All rights reserved.

# Semantic Kernel allows you multiple ways to setup your connectors.
# this sample shows that for OpenAI Connectors.

# After installing the semantic-kernel package
# you can use the following code to setup OpenAI Connector

# From environment settings
# using this method will try to find the required settings in the environment variables
# this is done using pydantic settings, see the full docs of that here: https://docs.pydantic.dev/latest/concepts/pydantic_settings/#usage
# We use a prefix for all the settings and then have names defined in the OpenAISettings class
# for OpenAI that is OPENAI_ as the prefix, with the following settings:
# - api_key (OPENAI_API_KEY): OpenAI API key, see https://platform.openai.com/account/api-keys
# - org_id (OPENAI_ORG_ID): This is usually optional unless your account belongs to multiple organizations.
# - chat_model_id (OPENAI_CHAT_MODEL_ID): The OpenAI chat model ID to use, for example, gpt-3.5-turbo or gpt-4,
# this variable is used in the OpenAIChatCompletion class and get's passed to the ai_model_id there.
# - text_model_id (OPENAI_TEXT_MODEL_ID): The OpenAI text model ID to use, for example, gpt-3.5-turbo-instruct,
# this variable is used in the OpenAITextCompletion class and get's passed to the ai_model_id there.
# - embedding_model_id (OPENAI_EMBEDDING_MODEL_ID): The embedding model ID to use, for example, text-embedding-ada-002,
# this variable is used in the OpenAITextEmbedding class and get's passed to the ai_model_id there.

import os

from pydantic import ValidationError

from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

try:
# when nothing is passed to the constructor,
# it will use the above environment variable names to find the required settings,
# in this case it will only fail if the OPENAI_CHAT_MODEL_ID and OPENAI_API_KEY are not found
service = OpenAIChatCompletion(service_id="openai_chat_service")
except ValidationError as e:
print(e)

# From a .env file
# when you want to store and use your settings from a specific file (any file as long as it is in the .env format)
# you can pass the path to the file to the constructor
# this will still look at the same names of the settings as above, but will try to load them from the file

try:
# this will try to load the settings from the file at the given path
service = OpenAIChatCompletion(service_id="openai_chat_service", env_file_path="path/to/env_file")
except ValidationError as e:
print(e)

# From a different value
# if you want to pass the settings yourself, you can do that by passing the values to the constructor
# this will ignore the environment variables and the .env file
# in this case our API_KEY is stored in a env variable called MY_API_KEY_VAR_NAME
# if using a file for this value, then we first need to uncomment and
# run the following code to load the .env file from the same folder as this file:
# from dotenv import load_dotenv
# dotenv_path = os.path.join(os.path.dirname(__file__), '.env')
# load_dotenv(dotenv_path)
# and after that pass the value directly to the constructor as shown below
# we can also fix another value, in this case the ai_model_id,
# which becomes chat_model_id in the settings, fixed to gpt-4o

try:
# this will use the given values as the settings
api_key = os.getenv("MY_API_KEY_VAR_NAME")
service = OpenAIChatCompletion(
service_id="openai_chat_service",
api_key=api_key,
ai_model_id="gpt-4o",
)
except ValidationError as e:
print(e)

# One final note:
# It is a convention that env settings are setup with all caps, and with underscores between words
# the loader that we use is case insensitive, so you can use any case you want in your env variables
# but it is a good practice to follow the convention and use all caps.
2 changes: 1 addition & 1 deletion python/semantic_kernel/connectors/memory/postgres/postgres_settings.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,6 @@ class PostgresSettings(KernelBaseSettings):
(Env var POSTGRES_CONNECTION_STRING)
"""

env_prefix: ClassVar[str] = "ASTRADB_"
env_prefix: ClassVar[str] = "POSTGRES_"

connection_string: SecretStr

0 comments on commit 1cc6464

Please sign in to comment.